R devel - Jan 2018 - Best practices in developing package: From a single file

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

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

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

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 <mehmet.suzen at gmail.com>
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