> >> 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,
~malcolm_c...@stowers.org
> >
> > 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
>
> ______________________________________________
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
