Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How do you write your package documentation? [closed]

Tags:

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 there 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?)

like image 353
Richie Cotton Avatar asked Jun 21 '10 15:06

Richie Cotton


People also ask

What is a documentation package?

Documentation Package means a compilation of historically significant records including, but not limited to, command operation reports, war diaries, and deck logs.

How do you run Roxygens?

There are three main ways to run roxygen: roxygen2::roxygenise() . devtools::document() . Ctrl + Shift + D , if you're using RStudio.

How do I read an R document?

To read a native R data file, if the file type is . rda , the format is automatically set to "R" . To invoke this option for a relevant data file of any file type, explicitly specify format="R" . Create a native R data file by saving the current data frame, usually mydata , with the lessR function Write .


2 Answers

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 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.

like image 118
Shane Avatar answered Sep 29 '22 04:09

Shane


Regarding roxygen resources, several more have since emerged, a few more have emerged, to quote my own notes:

Often when I google Roxygen or Roxygen2 I have trouble finding documentation. Here's a compilation of some key resources:

  • Hadley Wickham has a great introduction to core features of Roxygen 2

  • There are several vignettes listed on the Cran site for Roxygen 2

  • RStudio has notes on running Roxygen

  • roxygen2 package source code on github

like image 41
Jeromy Anglim Avatar answered Sep 29 '22 06:09

Jeromy Anglim