Best practices in developing package: From a single file

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
36 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Best practices in developing package: From a single file

Suzen, Mehmet-3
Dear R developers,

I am wondering what are the best practices for developing an R
package. I am aware of Hadley Wickham's best practice
documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
years ago there were some tools for generating a package out of a
single file, such as using package.skeleton, but no auto-generated
documentation. Do you know a way to generate documentation and a
package out of single R source file, or from an environment?

Many thanks,
Mehmet

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

braverock
On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
> Dear R developers,
>
> I am wondering what are the best practices for developing an R
> package. I am aware of Hadley Wickham's best practice
> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
> years ago there were some tools for generating a package out of a
> single file, such as using package.skeleton, but no auto-generated
> documentation. Do you know a way to generate documentation and a
> package out of single R source file, or from an environment?

Mehmet,

This list is for development of the R language itself and closely
related tools.  There is a separate list, R-pkg-devel, for development
of packages.  

Since you're here, I'll try to answer your question.

package.skeleton can create a package from all the R functions in a
specified environment.  So if you load all the functions that you want
in your new package into your R environment, then call
package.skeleton, you'll have a starting point.

At that point, I would probably recommend moving to RStudio, and using
RStudio to generate markdown comments for roxygen for all your newly
created function files.  Then you could finish off the documentation by
writing it in these roxygen skeletons or copying and pasting from
comments in your original code files.

Please address further discussion to the R-pkg-devel list.

Regards,

Brian

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Duncan Murdoch-2
On 30/01/2018 11:29 AM, Brian G. Peterson wrote:

> On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>> Dear R developers,
>>
>> I am wondering what are the best practices for developing an R
>> package. I am aware of Hadley Wickham's best practice
>> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
>> years ago there were some tools for generating a package out of a
>> single file, such as using package.skeleton, but no auto-generated
>> documentation. Do you know a way to generate documentation and a
>> package out of single R source file, or from an environment?
>
> Mehmet,
>
> This list is for development of the R language itself and closely
> related tools.  There is a separate list, R-pkg-devel, for development
> of packages.
>
> Since you're here, I'll try to answer your question.
>
> package.skeleton can create a package from all the R functions in a
> specified environment.  So if you load all the functions that you want
> in your new package into your R environment, then call
> package.skeleton, you'll have a starting point.
>
> At that point, I would probably recommend moving to RStudio, and using
> RStudio to generate markdown comments for roxygen for all your newly
> created function files.  Then you could finish off the documentation by
> writing it in these roxygen skeletons or copying and pasting from
> comments in your original code files.

I'd agree about moving to RStudio, but I think Roxygen is the wrong
approach for documentation.  package.skeleton() will have done the
boring mechanical part of setting up your .Rd files; all you have to do
is edit some content into them.  (Use prompt() to add a new file if you
add a new function later, don't run package.skeleton() again.)

This isn't the fashionable point of view, but I think it is easier to
get good documentation that way than using Roxygen.  (It's easier to get
bad documentation using Roxygen, but who wants that?)

The reason I think this is that good documentation requires work and
thought.  You need to think about the markup that will get your point
across, you need to think about putting together good examples, etc.
This is *harder* in Roxygen than if you are writing Rd files, because
Roxygen is a thin front end to produce Rd files from comments in your .R
files.  To get good stuff in the help page, you need just as much work
as in writing the .Rd file directly, but then you need to add another
layer on top to put in in a comment.  Most people don't bother.

I don't know any packages with what I'd consider to be good
documentation that use Roxygen.  It's just too easy to write minimal
documentation that passes checks, so Roxygen users don't keep refining it.

(There are plenty of examples of packages that write bad documentation
directly to .Rd as well.  I just don't know of examples of packages with
good documentation that use Roxygen.)

Based on my criticism last week of git and Github, I expect to be called
a grumpy old man for holding this point of view.  I'd actually like to
be proven wrong.  So to anyone who disagrees with me:  rather than just
calling me names, how about some examples of Roxygen-using packages that
have good help pages with good explanations, and good examples in them?

Back to Mehmet's question:  I think Hadley's book is pretty good, and
I'd recommend most of it, just not the Roxygen part.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Cook, Malcolm
> >> I am wondering what are the best practices for developing an R
 > >> package. I am aware of Hadley Wickham's best practice
 > >> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
 > >> years ago there were some tools for generating a package out of a
 > >> single file, such as using package.skeleton, but no auto-generated
 > >> documentation. Do you know a way to generate documentation and a
 > >> package out of single R source file, or from an environment?

I think you want to see the approach to generating a skeleton from a single .R file presented in:

        Simple and sustainable R packaging using inlinedocs http://inlinedocs.r-forge.r-project.org/

I have not used it in some time but found it invaluable when I did.

I would be VERY INTERESTED to hear how others feel it has held up.

Joining conversation late,

~[hidden email]

 > >
 > > Mehmet,
 > >
 > > This list is for development of the R language itself and closely
 > > related tools.  There is a separate list, R-pkg-devel, for development
 > > of packages.
 > >
 > > Since you're here, I'll try to answer your question.
 > >
 > > package.skeleton can create a package from all the R functions in a
 > > specified environment.  So if you load all the functions that you want
 > > in your new package into your R environment, then call
 > > package.skeleton, you'll have a starting point.
 > >
 > > At that point, I would probably recommend moving to RStudio, and using
 > > RStudio to generate markdown comments for roxygen for all your newly
 > > created function files.  Then you could finish off the documentation by
 > > writing it in these roxygen skeletons or copying and pasting from
 > > comments in your original code files.
 >
 > I'd agree about moving to RStudio, but I think Roxygen is the wrong
 > approach for documentation.  package.skeleton() will have done the
 > boring mechanical part of setting up your .Rd files; all you have to do
 > is edit some content into them.  (Use prompt() to add a new file if you
 > add a new function later, don't run package.skeleton() again.)
 >
 > This isn't the fashionable point of view, but I think it is easier to
 > get good documentation that way than using Roxygen.  (It's easier to get
 > bad documentation using Roxygen, but who wants that?)
 >
 > The reason I think this is that good documentation requires work and
 > thought.  You need to think about the markup that will get your point
 > across, you need to think about putting together good examples, etc.
 > This is *harder* in Roxygen than if you are writing Rd files, because
 > Roxygen is a thin front end to produce Rd files from comments in your .R
 > files.  To get good stuff in the help page, you need just as much work
 > as in writing the .Rd file directly, but then you need to add another
 > layer on top to put in in a comment.  Most people don't bother.
 >
 > I don't know any packages with what I'd consider to be good
 > documentation that use Roxygen.  It's just too easy to write minimal
 > documentation that passes checks, so Roxygen users don't keep refining it.
 >
 > (There are plenty of examples of packages that write bad documentation
 > directly to .Rd as well.  I just don't know of examples of packages with
 > good documentation that use Roxygen.)
 >
 > Based on my criticism last week of git and Github, I expect to be called
 > a grumpy old man for holding this point of view.  I'd actually like to
 > be proven wrong.  So to anyone who disagrees with me:  rather than just
 > calling me names, how about some examples of Roxygen-using packages
 > that
 > have good help pages with good explanations, and good examples in them?
 >
 > Back to Mehmet's question:  I think Hadley's book is pretty good, and
 > I'd recommend most of it, just not the Roxygen part.
 >
 > Duncan Murdoch
 >
 > ______________________________________________
 > [hidden email] mailing list
 > https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Dirk Eddelbuettel

Mehmet,

That is a loaded topic, not unlikely other topics preoccupying us these days.

There is package.skeleton() in base R as you already mentioned. It drove me
bonkers that it creates packages which then fail R CMD check, so I wrote a
wrapper package (pkgKitten) with another helper function (kitten()) which
calls the base R helper and then cleans up it---but otherwise remains
faithful to it.

These days pkgKitten defaults to creating per-package top-level help page
that just references content from DESCRIPTION via a set of newer Rd macros as
I find that helps keeping them aligned. The most recent example of mine is
  https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd 
I use either this function or the RStudio template helper all the time.

And similarly, other people written similar helpers. You may get other pointers.

And every couple of months someone writes a new tutorial about how to write a
first package. Then social media goes gaga and we get half a dozen blog posts
where someone celebrates finding said tutorial, reading it and following
through with a new package.

And many of us taught workshops on creating packages. There is a lot of
material out here, though lots of this material seems to be entirely ignorant
of what came before it.

And there has been lots, including Fritz's tutorial from a decade ago:

    https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
    https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf

So I'd recommend you just experiment and set up your own helpers. After all
the rule still holds: Anything you do more than three times should be a
function, and every function should be in a package. So customize _your_
function to create your package.

Dirk

--
http://dirk.eddelbuettel.com | @eddelbuettel | [hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Kenny Bell-2
In response to Duncan regarding the use of roxygen2 from the point of view
of a current user, I believe the issue he brings up is one of correlation
rather than causation.

Writing my first piece of R documentation was made much easier by using
roxygen2, and it shallowed the learning curve substantially.

What Duncan may be observing is a general tendency of roxygen2 users to
write overly concise documentation. However, I believe this to be caused by
an omitted variable - likely the tendency of roxygen2 users to want outputs
quickly. I can't see anything in roxygen2 that might suggest a causal link
but I'd be interested in hearing specific examples.

FWIW, I've also heard the same documentation criticism leveled at R in
general (mostly from Stata and MATLAB users).

Kenny

On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel <[hidden email]> wrote:

>
> Mehmet,
>
> That is a loaded topic, not unlikely other topics preoccupying us these
> days.
>
> There is package.skeleton() in base R as you already mentioned. It drove me
> bonkers that it creates packages which then fail R CMD check, so I wrote a
> wrapper package (pkgKitten) with another helper function (kitten()) which
> calls the base R helper and then cleans up it---but otherwise remains
> faithful to it.
>
> These days pkgKitten defaults to creating per-package top-level help page
> that just references content from DESCRIPTION via a set of newer Rd macros
> as
> I find that helps keeping them aligned. The most recent example of mine is
>   https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
> I use either this function or the RStudio template helper all the time.
>
> And similarly, other people written similar helpers. You may get other
> pointers.
>
> And every couple of months someone writes a new tutorial about how to
> write a
> first package. Then social media goes gaga and we get half a dozen blog
> posts
> where someone celebrates finding said tutorial, reading it and following
> through with a new package.
>
> And many of us taught workshops on creating packages. There is a lot of
> material out here, though lots of this material seems to be entirely
> ignorant
> of what came before it.
>
> And there has been lots, including Fritz's tutorial from a decade ago:
>
>     https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>     https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>
> So I'd recommend you just experiment and set up your own helpers. After all
> the rule still holds: Anything you do more than three times should be a
> function, and every function should be in a package. So customize _your_
> function to create your package.
>
> Dirk
>
> --
> http://dirk.eddelbuettel.com | @eddelbuettel | [hidden email]
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Suzen, Mehmet-3
In reply to this post by Suzen, Mehmet-3
Dear All,

Thank you for all valuable input and sorry for the off-topic for the
list. I will try R-pkg-devel for further related questions.   I was
actually after "one-go" auto-documentation in-line or out of comments
from a single file/environment in a similar spirit to
'package.skeleton or an extension of it. My take-home message or
summary from all responses do far.

* Regarding documentation;Duncan Murdoch's  wisdom "...to get good
stuff in the help page, you need just as much work as in writing the
.Rd file directly..". So there is no silver bullet in terms of
auto-documentation, I gather, especially for considering if one uses
more complex constructs, S4/S6 classes or Rcpp code behind.On the
other hand, roxgen2 being the most comprehensive solution.

* Lightweight solution to try out before moving to RStudio fully. I
will give a try Dirk's 'pkgKitten' and 'inlinedocs' Malcolm mentioned.

Interestingly, responses have reminded me Larry Wall's quote
(https://en.wikipedia.org/wiki/There%27s_more_than_one_way_to_do_it),
which I think really applies to R more than any language I encounter
so far, from different class systems to different time-series
representations, so richly democratised.

Many regards,
Mehmet


On 30 January 2018 at 17:00, Suzen, Mehmet <[hidden email]> wrote:

> Dear R developers,
>
> I am wondering what are the best practices for developing an R
> package. I am aware of Hadley Wickham's best practice
> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
> years ago there were some tools for generating a package out of a
> single file, such as using package.skeleton, but no auto-generated
> documentation. Do you know a way to generate documentation and a
> package out of single R source file, or from an environment?
>
> Many thanks,
> Mehmet

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Suzen, Mehmet-3
In reply to this post by Cook, Malcolm
On 30 January 2018 at 21:31, Cook, Malcolm <[hidden email]> wrote:
>
> I think you want to see the approach to generating a skeleton from a single .R file presented in:
>
>         Simple and sustainable R packaging using inlinedocs http://inlinedocs.r-forge.r-project.org/
>
> I have not used it in some time but found it invaluable when I did.

For the record, the package has a JSS article as well:

https://www.jstatsoft.org/article/view/v054i06


Best,
-m

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Duncan Murdoch-2
In reply to this post by Kenny Bell-2
On 30/01/2018 4:30 PM, Kenny Bell wrote:
> In response to Duncan regarding the use of roxygen2 from the point of view
> of a current user, I believe the issue he brings up is one of correlation
> rather than causation.

Could be.  However, I think editing comments in a .R file is a bit
harder than editing text in a .Rd file, so I think the format
discourages editing.  I think it does make it easier to pass R CMD check
the first time, but I don't think you should be satisfied with that.

What would probably change my mind would be a two-way (or multi-way)
tool:  it takes input in Roxygen comments or Rd files (or something
else), and produces another format.  Then I'd probably choose to write
the first pass in Roxygen, and convert to Rd for editing.  Other people
might go in the opposite direction.  Or someone might write a fancy
WYSIWYG editor for people who like that style of editing.

A couple of years ago I was hoping someone would figure out a way to
create help page input in R Markdown, but I think that's tricky because
of the lack of semantic markup there.  There *was* a project last year
to work on other input methods; I dropped out before it got very far,
and I don't know its current status.

>
> Writing my first piece of R documentation was made much easier by using
> roxygen2, and it shallowed the learning curve substantially.

I'm not completely up to date on Roxygen2 these days:  can you do some
pages in Rd, others in Roxygen?  That's not quite as good as being able
to switch back and forth, but it would allow you to start in Roxygen,
then gradually move to Rd when editing there was easier.

>
> What Duncan may be observing is a general tendency of roxygen2 users to
> write overly concise documentation. However, I believe this to be caused by
> an omitted variable - likely the tendency of roxygen2 users to want outputs
> quickly. I can't see anything in roxygen2 that might suggest a causal link
> but I'd be interested in hearing specific examples.

I don't know about that.  *Everyone* wants output quickly.

Duncan Murdoch


> FWIW, I've also heard the same documentation criticism leveled at R in
> general (mostly from Stata and MATLAB users).
>
> Kenny
>
> On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel <[hidden email]> wrote:
>
>>
>> Mehmet,
>>
>> That is a loaded topic, not unlikely other topics preoccupying us these
>> days.
>>
>> There is package.skeleton() in base R as you already mentioned. It drove me
>> bonkers that it creates packages which then fail R CMD check, so I wrote a
>> wrapper package (pkgKitten) with another helper function (kitten()) which
>> calls the base R helper and then cleans up it---but otherwise remains
>> faithful to it.
>>
>> These days pkgKitten defaults to creating per-package top-level help page
>> that just references content from DESCRIPTION via a set of newer Rd macros
>> as
>> I find that helps keeping them aligned. The most recent example of mine is
>>    https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
>> I use either this function or the RStudio template helper all the time.
>>
>> And similarly, other people written similar helpers. You may get other
>> pointers.
>>
>> And every couple of months someone writes a new tutorial about how to
>> write a
>> first package. Then social media goes gaga and we get half a dozen blog
>> posts
>> where someone celebrates finding said tutorial, reading it and following
>> through with a new package.
>>
>> And many of us taught workshops on creating packages. There is a lot of
>> material out here, though lots of this material seems to be entirely
>> ignorant
>> of what came before it.
>>
>> And there has been lots, including Fritz's tutorial from a decade ago:
>>
>>      https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>>      https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>>
>> So I'd recommend you just experiment and set up your own helpers. After all
>> the rule still holds: Anything you do more than three times should be a
>> function, and every function should be in a package. So customize _your_
>> function to create your package.
>>
>> Dirk
>>
>> --
>> http://dirk.eddelbuettel.com | @eddelbuettel | [hidden email]
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>
> [[alternative HTML version deleted]]
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Duncan Murdoch-2
In reply to this post by Dirk Eddelbuettel
On 30/01/2018 4:12 PM, Dirk Eddelbuettel wrote:

>
> Mehmet,
>
> That is a loaded topic, not unlikely other topics preoccupying us these days.
>
> There is package.skeleton() in base R as you already mentioned. It drove me
> bonkers that it creates packages which then fail R CMD check, so I wrote a
> wrapper package (pkgKitten) with another helper function (kitten()) which
> calls the base R helper and then cleans up it---but otherwise remains
> faithful to it.

Failing R CMD check isn't a big deal:  you want to be reminded to edit
those incomplete help files.  But I think I recall that you couldn't
even build the package that package.skeleton() created, and that indeed
would be irritating, especially if you had a lot of functions so you had
a lot of cleanup to do.  I don't know if that's still true because I
generally use RStudio to create the initial package structure rather
than calling package.skeleton myself.

Duncan Murdoch

>
> These days pkgKitten defaults to creating per-package top-level help page
> that just references content from DESCRIPTION via a set of newer Rd macros as
> I find that helps keeping them aligned. The most recent example of mine is
>    https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
> I use either this function or the RStudio template helper all the time.
>
> And similarly, other people written similar helpers. You may get other pointers.
>
> And every couple of months someone writes a new tutorial about how to write a
> first package. Then social media goes gaga and we get half a dozen blog posts
> where someone celebrates finding said tutorial, reading it and following
> through with a new package.
>
> And many of us taught workshops on creating packages. There is a lot of
> material out here, though lots of this material seems to be entirely ignorant
> of what came before it.
>
> And there has been lots, including Fritz's tutorial from a decade ago:
>
>      https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>      https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>
> So I'd recommend you just experiment and set up your own helpers. After all
> the rule still holds: Anything you do more than three times should be a
> function, and every function should be in a package. So customize _your_
> function to create your package.
>
> Dirk
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

hadley wickham
In reply to this post by Duncan Murdoch-2
On Tue, Jan 30, 2018 at 4:55 PM, Duncan Murdoch
<[hidden email]> wrote:

> On 30/01/2018 4:30 PM, Kenny Bell wrote:
>>
>> In response to Duncan regarding the use of roxygen2 from the point of view
>> of a current user, I believe the issue he brings up is one of correlation
>> rather than causation.
>
>
> Could be.  However, I think editing comments in a .R file is a bit harder
> than editing text in a .Rd file, so I think the format discourages editing.
> I think it does make it easier to pass R CMD check the first time, but I
> don't think you should be satisfied with that.

One counter-point: I find it much easier to remember to update the
documentation when you update the code, if the code and the
documentation are very close together. I think mingling code and
documentation in the same file does add a subtle pressure to write
shorter docs, but I'm not entirely sure that's a bad thing - for long
form writing, vignettes are a much better solution anyway (since you
often want to mingle code and explanation).

Personally, I don't find writing in comments any harder than writing
in .Rd files, especially now that you can write in markdown and have
it automatically translated to Rd formatting commands.  And on the
negative side of Rd, I find it frustrating to have to copy and paste
the function definition to the usage section every time I modify an
argument. It just feels like unnecessary busywork that the computer
should be able to do for me (although I do understand why it is not
possible).

>> Writing my first piece of R documentation was made much easier by using
>> roxygen2, and it shallowed the learning curve substantially.
>
> I'm not completely up to date on Roxygen2 these days:  can you do some pages
> in Rd, others in Roxygen?  That's not quite as good as being able to switch
> back and forth, but it would allow you to start in Roxygen, then gradually
> move to Rd when editing there was easier.

Yes, that's possible, and to protect you in mixed environment,
roxygen2 will never overwrite a file that it did not itself create.

Hadley

--
http://hadley.nz

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

hadley wickham
In reply to this post by Duncan Murdoch-2
>> There is package.skeleton() in base R as you already mentioned. It drove
>> me
>> bonkers that it creates packages which then fail R CMD check, so I wrote a
>> wrapper package (pkgKitten) with another helper function (kitten()) which
>> calls the base R helper and then cleans up it---but otherwise remains
>> faithful to it.
>
>
> Failing R CMD check isn't a big deal:  you want to be reminded to edit those
> incomplete help files.  But I think I recall that you couldn't even build
> the package that package.skeleton() created, and that indeed would be
> irritating, especially if you had a lot of functions so you had a lot of
> cleanup to do.  I don't know if that's still true because I generally use
> RStudio to create the initial package structure rather than calling
> package.skeleton myself.

Personally, I think the biggest problem with package.skeleton() is
that it assumes that the source of truth is objects in an environment.
This seems the wrong way around to me.

Hadley

--
http://hadley.nz

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Joris FA Meys
In reply to this post by Duncan Murdoch-2
Dear Duncan,

With all respect, but I strongly disagree on your stance regarding roxygen2
for multiple reasons:

1. It is in my humble opinion not correct to evaluate a tool based on the
abuse of some users. It's not because people write packages with bad
documentation, that roxygen2 is to blame. I use roxygen2, and I care a
great deal about documentation. So I actually took a bit offense there.

2. Writing .Rd files directly means that you have to write out the usage
yourself, know the different tags needed for documenting different types of
generics and methods, and so forth. It means a lot more iterations to get
every tag right so that R CMD check does not complain any more. It requires
a more detailed knowledge of the entire Rd tag system compared to letting
roxygen2 do the standard work for you. So one could argue that the extra
knowledge required would actually hinder starting developers to write good
documentation as opposed to help them.

3. given your criticism, I'd like your opinion on where I can improve the
documentation of https://github.com/CenterForStatistics-UGent/pim. I'm
currently busy updating the help files for a next release on CRAN, so your
input is more than welcome.

I'm not going to force anyone to use roxygen2. But I personally find it
easier to have the function right below the documentation, so that any
change to the function can immediately be documented as well. You prefer to
do this by keeping that strictly separated, which is absolutely fine. It's
just not my prefered workflow. Different animal, different habits I guess.

On a sidenote: I had a lot of complaints about earlier iterations of
roxygen2 and the many changes to tags and their meanings, but the roxygen2
package matured in the meantime and has been a stable and reliable tool for
me the past years.

Kind regards
Joris



On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch <[hidden email]>
wrote:

> On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
>
>> On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>>
>>> Dear R developers,
>>>
>>> I am wondering what are the best practices for developing an R
>>> package. I am aware of Hadley Wickham's best practice
>>> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
>>> years ago there were some tools for generating a package out of a
>>> single file, such as using package.skeleton, but no auto-generated
>>> documentation. Do you know a way to generate documentation and a
>>> package out of single R source file, or from an environment?
>>>
>>
>> Mehmet,
>>
>> This list is for development of the R language itself and closely
>> related tools.  There is a separate list, R-pkg-devel, for development
>> of packages.
>>
>> Since you're here, I'll try to answer your question.
>>
>> package.skeleton can create a package from all the R functions in a
>> specified environment.  So if you load all the functions that you want
>> in your new package into your R environment, then call
>> package.skeleton, you'll have a starting point.
>>
>> At that point, I would probably recommend moving to RStudio, and using
>> RStudio to generate markdown comments for roxygen for all your newly
>> created function files.  Then you could finish off the documentation by
>> writing it in these roxygen skeletons or copying and pasting from
>> comments in your original code files.
>>
>
> I'd agree about moving to RStudio, but I think Roxygen is the wrong
> approach for documentation.  package.skeleton() will have done the boring
> mechanical part of setting up your .Rd files; all you have to do is edit
> some content into them.  (Use prompt() to add a new file if you add a new
> function later, don't run package.skeleton() again.)
>
> This isn't the fashionable point of view, but I think it is easier to get
> good documentation that way than using Roxygen.  (It's easier to get bad
> documentation using Roxygen, but who wants that?)
>
> The reason I think this is that good documentation requires work and
> thought.  You need to think about the markup that will get your point
> across, you need to think about putting together good examples, etc.
> This is *harder* in Roxygen than if you are writing Rd files, because
> Roxygen is a thin front end to produce Rd files from comments in your .R
> files.  To get good stuff in the help page, you need just as much work as
> in writing the .Rd file directly, but then you need to add another layer on
> top to put in in a comment.  Most people don't bother.
>
> I don't know any packages with what I'd consider to be good documentation
> that use Roxygen.  It's just too easy to write minimal documentation that
> passes checks, so Roxygen users don't keep refining it.
>
> (There are plenty of examples of packages that write bad documentation
> directly to .Rd as well.  I just don't know of examples of packages with
> good documentation that use Roxygen.)
>
> Based on my criticism last week of git and Github, I expect to be called a
> grumpy old man for holding this point of view.  I'd actually like to be
> proven wrong.  So to anyone who disagrees with me:  rather than just
> calling me names, how about some examples of Roxygen-using packages that
> have good help pages with good explanations, and good examples in them?
>
> Back to Mehmet's question:  I think Hadley's book is pretty good, and I'd
> recommend most of it, just not the Roxygen part.
>
> Duncan Murdoch
>
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>



--
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>

-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Duncan Murdoch-2
In reply to this post by hadley wickham
On 30/01/2018 11:39 PM, Hadley Wickham wrote:

> On Tue, Jan 30, 2018 at 4:55 PM, Duncan Murdoch
> <[hidden email]> wrote:
>> On 30/01/2018 4:30 PM, Kenny Bell wrote:
>>>
>>> In response to Duncan regarding the use of roxygen2 from the point of view
>>> of a current user, I believe the issue he brings up is one of correlation
>>> rather than causation.
>>
>>
>> Could be.  However, I think editing comments in a .R file is a bit harder
>> than editing text in a .Rd file, so I think the format discourages editing.
>> I think it does make it easier to pass R CMD check the first time, but I
>> don't think you should be satisfied with that.
>
> One counter-point: I find it much easier to remember to update the
> documentation when you update the code, if the code and the
> documentation are very close together. I think mingling code and
> documentation in the same file does add a subtle pressure to write
> shorter docs, but I'm not entirely sure that's a bad thing - for long
> form writing, vignettes are a much better solution anyway (since you
> often want to mingle code and explanation).

I agree about your first point to some extent, but it works best when
the documentation is short.  Once you get a long help page, you still
have the long distance.  Some functions need long help pages because
they do a lot.

RStudio provides pretty good support for both forms of documentation.
If I've just modified a function, I can type the name of the function in
the "Go to file/function" box at the top, and go directly to the right
.Rd file.  That reduces the "distance".  I imagine ESS and other editors
have (or could have) something similar.

Regarding vignettes versus help pages:  I think they have different
purposes.  You want the technical documentation in the help page to be
really complete, to explain what each parameter does, what the value is,
with simple examples.  I won't try to embarrass anyone with specific
examples (unless someone volunteers ;-), but I would say the general
trend in Roxygen-using packages is to be quite incomplete, with one-line
parameter descriptions being all you get.  Sometimes this is sufficient,
but often it isn't.  The goal appears to be to pass checks, not to write
good documentation.  Some wild speculation:  maybe the proximity to the
source makes authors think the source is visible to the user looking for
help.

Vignettes get to leave out rarely used parameters, but get to show how
things are used in longer examples, combining multiple functions.  I've
tried to write the rgl documentation this way, with links from the
vignette to the help pages.

I haven't added links from the help page to the location in the vignette
where the function is put in context, but that's probably possible
(provided HTML help is used, and the vignette is in HTML).

> Personally, I don't find writing in comments any harder than writing
> in .Rd files, especially now that you can write in markdown and have
> it automatically translated to Rd formatting commands.  

I didn't know about the possibility of Markdown.  That's a good thing.
You didn't say what editor you use, but RStudio is a good guess, and it
also makes it easier to write in comments.

And on the
> negative side of Rd, I find it frustrating to have to copy and paste
> the function definition to the usage section every time I modify an
> argument. It just feels like unnecessary busywork that the computer
> should be able to do for me (although I do understand why it is not
> possible).

The computer (via R CMD check) does tell you what is missing.  I'd guess
that the transfer could be done automatically, but it would be in a very
editor-specific way, e.g. an RStudio add-in, or Emacs macro, or
whatever.  Someone should write it :-).

>
>>> Writing my first piece of R documentation was made much easier by using
>>> roxygen2, and it shallowed the learning curve substantially.
>>
>> I'm not completely up to date on Roxygen2 these days:  can you do some pages
>> in Rd, others in Roxygen?  That's not quite as good as being able to switch
>> back and forth, but it would allow you to start in Roxygen, then gradually
>> move to Rd when editing there was easier.
>
> Yes, that's possible, and to protect you in mixed environment,
> roxygen2 will never overwrite a file that it did not itself create.

Good!  Perhaps I should give it another look.

Duncan

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Duncan Murdoch-2
In reply to this post by Joris FA Meys
On 31/01/2018 6:33 AM, Joris Meys wrote:
> Dear Duncan,
>
> With all respect, but I strongly disagree on your stance regarding
> roxygen2 for multiple reasons:
>
> 1. It is in my humble opinion not correct to evaluate a tool based on
> the abuse of some users. It's not because people write packages with bad
> documentation, that roxygen2 is to blame. I use roxygen2, and I care a
> great deal about documentation. So I actually took a bit offense there.

Sorry about that.  I did say I wanted to be proven wrong.

> 2. Writing .Rd files directly means that you have to write out the usage
> yourself, know the different tags needed for documenting different types
> of generics and methods, and so forth.

Not at all --- that's what the prompt() function does.

> It means a lot more iterations to
> get every tag right so that R CMD check does not complain any more. It
> requires a more detailed knowledge of the entire Rd tag system compared
> to letting roxygen2 do the standard work for you. So one could argue
> that the extra knowledge required would actually hinder starting
> developers to write good documentation as opposed to help them.

New users (and old users) should use prompt() to set up the basic help page.

There are situations where prompt() doesn't help, namely edits to
existing pages:

  - adding a second function.
  - adding new parameters.

I think the infrastructure is there to allow functions to be written to
do these things, but as far as I know nobody has done it.

>
> 3. given your criticism, I'd like your opinion on where I can improve
> the documentation of https://github.com/CenterForStatistics-UGent/pim.
> I'm currently busy updating the help files for a next release on CRAN,
> so your input is more than welcome.

Sure, I'll take a look.

> I'm not going to force anyone to use roxygen2. But I personally find it
> easier to have the function right below the documentation, so that any
> change to the function can immediately be documented as well. You prefer
> to do this by keeping that strictly separated, which is absolutely fine.
> It's just not my prefered workflow. Different animal, different habits I
> guess.
>
> On a sidenote: I had a lot of complaints about earlier iterations of
> roxygen2 and the many changes to tags and their meanings, but the
> roxygen2 package matured in the meantime and has been a stable and
> reliable tool for me the past years.

I formed my opinion several years ago, so perhaps I should take another
look.  One problem is lock-in:  once you write an Rd file, you can't (as
far as I know) easily import it as Roxygen markup.  So I'd have to start
a new package to get experience with Roxygen.  Maybe it should be the
package that adds the Rd tools mentioned above :-).

Duncan Murdoch

>
> Kind regards
> Joris
>
>
>
> On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch
> <[hidden email] <mailto:[hidden email]>> wrote:
>
>     On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
>
>         On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>
>             Dear R developers,
>
>             I am wondering what are the best practices for developing an R
>             package. I am aware of Hadley Wickham's best practice
>             documentation/book (http://r-pkgs.had.co.nz/).  I recall a
>             couple of
>             years ago there were some tools for generating a package out
>             of a
>             single file, such as using package.skeleton, but no
>             auto-generated
>             documentation. Do you know a way to generate documentation and a
>             package out of single R source file, or from an environment?
>
>
>         Mehmet,
>
>         This list is for development of the R language itself and closely
>         related tools.  There is a separate list, R-pkg-devel, for
>         development
>         of packages.
>
>         Since you're here, I'll try to answer your question.
>
>         package.skeleton can create a package from all the R functions in a
>         specified environment.  So if you load all the functions that
>         you want
>         in your new package into your R environment, then call
>         package.skeleton, you'll have a starting point.
>
>         At that point, I would probably recommend moving to RStudio, and
>         using
>         RStudio to generate markdown comments for roxygen for all your newly
>         created function files.  Then you could finish off the
>         documentation by
>         writing it in these roxygen skeletons or copying and pasting from
>         comments in your original code files.
>
>
>     I'd agree about moving to RStudio, but I think Roxygen is the wrong
>     approach for documentation.  package.skeleton() will have done the
>     boring mechanical part of setting up your .Rd files; all you have to
>     do is edit some content into them.  (Use prompt() to add a new file
>     if you add a new function later, don't run package.skeleton() again.)
>
>     This isn't the fashionable point of view, but I think it is easier
>     to get good documentation that way than using Roxygen.  (It's easier
>     to get bad documentation using Roxygen, but who wants that?)
>
>     The reason I think this is that good documentation requires work and
>     thought.  You need to think about the markup that will get your
>     point across, you need to think about putting together good
>     examples, etc.
>     This is *harder* in Roxygen than if you are writing Rd files,
>     because Roxygen is a thin front end to produce Rd files from
>     comments in your .R files.  To get good stuff in the help page, you
>     need just as much work as in writing the .Rd file directly, but then
>     you need to add another layer on top to put in in a comment.  Most
>     people don't bother.
>
>     I don't know any packages with what I'd consider to be good
>     documentation that use Roxygen.  It's just too easy to write minimal
>     documentation that passes checks, so Roxygen users don't keep
>     refining it.
>
>     (There are plenty of examples of packages that write bad
>     documentation directly to .Rd as well.  I just don't know of
>     examples of packages with good documentation that use Roxygen.)
>
>     Based on my criticism last week of git and Github, I expect to be
>     called a grumpy old man for holding this point of view.  I'd
>     actually like to be proven wrong.  So to anyone who disagrees with
>     me:  rather than just calling me names, how about some examples of
>     Roxygen-using packages that have good help pages with good
>     explanations, and good examples in them?
>
>     Back to Mehmet's question:  I think Hadley's book is pretty good,
>     and I'd recommend most of it, just not the Roxygen part.
>
>     Duncan Murdoch
>
>
>     ______________________________________________
>     [hidden email] <mailto:[hidden email]> mailing list
>     https://stat.ethz.ch/mailman/listinfo/r-devel
>     <https://stat.ethz.ch/mailman/listinfo/r-devel>
>
>
>
>
> --
> Joris Meys
> Statistical consultant
>
> Department of Data Analysis and Mathematical Modelling
> Ghent University
> Coupure Links 653, B-9000 Gent (Belgium)
> <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>
>
> -----------
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> -------------------------------
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Duncan Murdoch-2
In reply to this post by Joris FA Meys
On 31/01/2018 6:33 AM, Joris Meys wrote:

> 3. given your criticism, I'd like your opinion on where I can improve
> the documentation of https://github.com/CenterForStatistics-UGent/pim.
> I'm currently busy updating the help files for a next release on CRAN,
> so your input is more than welcome.

After this invitation I sent some private comments to Joris.  I would
say his package does a pretty good job of documentation; it isn't the
kind of Roxygen-using package that I was complaining about.  So I will
say I have received an example of a Roxygen-using package that
has good help pages.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Dirk Eddelbuettel
In reply to this post by hadley wickham

(Please do not quote without attribution)

On 30 January 2018 at 20:44, Hadley Wickham wrote:
| Personally, I think the biggest problem with package.skeleton() is
| that it assumes that the source of truth is objects in an environment.
| This seems the wrong way around to me.

Basically irrelevant as it is optional behaviour.  With various packages at
work I may by now have created several dozen packages via package.skeleton(),
and I essentially never submitted an existing function.

Dirk

--
http://dirk.eddelbuettel.com | @eddelbuettel | [hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Joris FA Meys
In reply to this post by Duncan Murdoch-2
On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <[hidden email]>
wrote:

> On 31/01/2018 6:33 AM, Joris Meys wrote:
>
> 3. given your criticism, I'd like your opinion on where I can improve the
>> documentation of https://github.com/CenterForStatistics-UGent/pim. I'm
>> currently busy updating the help files for a next release on CRAN, so your
>> input is more than welcome.
>>
>
> After this invitation I sent some private comments to Joris.  I would say
> his package does a pretty good job of documentation; it isn't the kind of
> Roxygen-using package that I was complaining about.  So I will say I have
> received an example of a Roxygen-using package that
> has good help pages.
>

Thank you for the nice compliment and the valuable tips.

--
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>

-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Mark van der Loo
I fully agree with Joris and Hadley on roxygen2.


Additionally:

I wrote and published my first package before roxygen (or roxygen2) was
available. I found editing .Rd extremely terse (especially when code is
updated). For example, the fact that there are no spaces allowed between }
and { in \param{}{} has hurt my brain quite a few times, especially since R
CMD check did not give any useful error messages about it. For me it is a
signal that the Rd parser is rather primitive. On the other hand Roxygen2
now usually gives pretty good error messages when I syntax error something.

Also, the 'parent' of roxygen is Doxygen, which was already widely used
(also by me) in the C/C++ community before roxygen was published. I cannot
remember anyone ever complaining about C/C++ documentation deteriorating
because of Doxygen.


-Mark


Op wo 31 jan. 2018 om 14:02 schreef Joris Meys <[hidden email]>:

> On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <[hidden email]>
> wrote:
>
> > On 31/01/2018 6:33 AM, Joris Meys wrote:
> >
> > 3. given your criticism, I'd like your opinion on where I can improve the
> >> documentation of https://github.com/CenterForStatistics-UGent/pim. I'm
> >> currently busy updating the help files for a next release on CRAN, so
> your
> >> input is more than welcome.
> >>
> >
> > After this invitation I sent some private comments to Joris.  I would say
> > his package does a pretty good job of documentation; it isn't the kind of
> > Roxygen-using package that I was complaining about.  So I will say I have
> > received an example of a Roxygen-using package that
> > has good help pages.
> >
>
> Thank you for the nice compliment and the valuable tips.
>
> --
> Joris Meys
> Statistical consultant
>
> Department of Data Analysis and Mathematical Modelling
> Ghent University
> Coupure Links 653, B-9000 Gent (Belgium)
> <
> https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g
> >
>
> -----------
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> -------------------------------
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Best practices in developing package: From a single file

Pfaff, Bernhard Dr.
In reply to this post by Joris FA Meys
Dear All:

stepping in late, but @Joris, if you would like to take 'from a single file' literally,
have a look at:

        https://github.com/bpfaff/lp4rp

(lp4rp: literate programming for R packages);

Cheers,
Bernhard

ps:  incidentally, within the noweb-file roxygen is employed.

-----Ursprüngliche Nachricht-----
Von: R-devel [mailto:[hidden email]] Im Auftrag von Joris Meys
Gesendet: Mittwoch, 31. Januar 2018 14:02
An: Duncan Murdoch
Cc: r-devel
Betreff: [EXT] Re: [Rd] Best practices in developing package: From a single file

On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <[hidden email]>
wrote:

> On 31/01/2018 6:33 AM, Joris Meys wrote:
>
> 3. given your criticism, I'd like your opinion on where I can improve
> the
>> documentation of https://github.com/CenterForStatistics-UGent/pim.
>> I'm currently busy updating the help files for a next release on
>> CRAN, so your input is more than welcome.
>>
>
> After this invitation I sent some private comments to Joris.  I would
> say his package does a pretty good job of documentation; it isn't the
> kind of Roxygen-using package that I was complaining about.  So I will
> say I have received an example of a Roxygen-using package that has
> good help pages.
>

Thank you for the nice compliment and the valuable tips.

--
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling Ghent University Coupure Links 653, B-9000 Gent (Belgium) <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>

-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
*****************************************************************
Confidentiality Note: The information contained in this ...{{dropped:10}}

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
12