How do you write your package documentation?

Question

I haven't quite figured out a sensible workflow for building packages and writing their documentation.

I want as much of the process (and the documentation) as possible to be automatically generated.

The obvious way to do this seems to be to use package.skeleton to create the basic package files, then programmatically overwrite the DESCRIPTION file and the Rd files. The trouble with this is that you then lose the automatically generated fields that ensure you've remembered to document all the right parameters.

I'd like to know how you go about building packages and writing documentation. Are their any tools available to make the process easier? (roxygen looks like it was designed for this sort of thing; is there a good tutorial for it? and are there any alternatives?)

Answer 1

I use roxygen for all my projects. For an example, browse the source for the webvis package. Hadley also uses roxygen for his documentation (e.g. see his lubridate package).

To the best of my knowledge, roxygen isn't documented much beyond the vigette (have a look at the roxygen homepage).

Roxygen is good because it leads to literate programming, in the sense that your documentation and code are side-by-side. This also makes the documentation process a little easier since you're working with everything at once. I definitely recommend it, and won't develop any packages without it at this point.

That said, it doesn't automate the documentation in the sense that some documentation-generation tools do (e.g. javadoc): roxygen interprets R comments that are properly formatted, but it doesn't interpret R code in a any way.

Regarding the creation of the package generally: package-skeleton is great for starters. Once you have created a few packages you may find it easier in the future just to create all the directories, NAMESPACE, etc. by hand. Especially if you are going to follow some of the other practices, such as including a demo directory, using roxygen, writing a vignette, or including source code in other languages.

Lastly, I manage my packages in Eclipse (StatET); many of the IDE's have "project" views that help managing the package structure, so you might also want to use a more advanced editor.