We all know that documenting our code is important, but equally important is to be able to read that documentation. If you use R, you know that the help feature (?function) is essential. If you organize your code into an R package, it is super easy to create help files that you and users can use to call up using ?. Documenting code may sound like a snoozer of a topic, but using the roxygen2 package and diligently writing documentation for my functions and data is one of the top 3 habits that has made my coding more efficient. You can also document all your data in the same way.
For more help on roxygen2, see the section in Hadley Wickham’s book R Packages on Roxygen. Here’s a short cheatsheet Roxygen helper. Also Roxygen has good tutorials and help. Type
browseVignettes(package="roxygen2")to open a browser window with links to the tutorials.
roxygen2 (and the the ‘Build and Install’ step) will create the help files that users access with `?function.name.
The same man files are also used to create a package manual, e.g. https://cran.r-project.org/web/packages/MARSS/MARSS.pdf
And it generates the navigation page for all the documentation
help(package="forecast")The man files are also used by pkgdown to make a website version of your documentation. Here is an example of a pkgdown-generated webpage for the FIT R package r4MAS.
SardineForecast is an example of a package that is purely personal. It is for the data, and a few utility functions, for a group of researchers working with a shared set of data.
help(package="SardineForecast")r4MAS is an example of a FIT public R package.
install.packages("roxygen2")Open your test package, MyNewPackage. If you made this last week, you can open RStudio and then click the little arrow next to the blue cube in the top right corner. Or you can clone it (click the little + in top right in GitHub, select Import, and paste in the URL).
Set the Project Build Options to use Roxygen
Tools > Project Options… > Build Tools > then check the checkbox “Generate documentation with Roxygen”. Then click “Configure”. Check the box at the bottom for “Install and Restart”.
Make sure your DESCRIPTION file has these lines:
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.1Roxygen comments with #' are put at the top of your function, in the same file. They have a standard format and standard sections. There is a bit of customization you can do, but the following basic form will cover 95% of your needs. Read this for details.
#' @title Short title
#'
#' @description
#' Description should be one paragraph. Put details in details.
#'
#' @details
#' Optional if you want to add more detais.J
#'
#' @param param.name1 Describe all your function arguments
#' @param param.name2 Describe all your function arguments
#'
#' @examples
#' # provide some examples of how to use your function
#' hello()
#'
#' @seealso List relevant other functions [littleforecast()].
#'
#` @references
#' List references
#' @export
yourfunction <- function(param.name1, param.name2){}@title and @description can be left off (not the text, just the @…. part), but title text should be in line 1, then a blank line (#’ only), and then the description text. The only required elements are @title, @description, and @param (defining the function arguments).
@export means that your function is added to your NAMESPACE so is not hidden. Just include this for now.
hello()First remove the old hello.Rd file from the man folder. That is there because when we created our new package using RStudio’s template, we didn’t select ‘use Roxygen’ so it added a manually created help (i.e. Rd) file for us in the man folder. Now we are going to use Roxygen, so we need to remove that file.
Copy and paste this to the top of hello.r in the R folder. Replace all the comments at the top with these lines.
#' Hello World!
#'
#' Prints a the classic first program greeting. It takes no arguments.
#'
#' @examples
#' hello()
#' @exportTo build the documentation, click ‘Install and Restart’ from the Build tab.
Once you see that MyNewPackage is reloaded (library(MyNewPackage) appears on the command line), you can type ?hello to get the help info.
Roxygen will complain that the NAMESPACE was not generated by Roxygen so it is ignoring our @export. Let’s delete the NAMESPACE file and try again.
When you update the documentation or add new documentation, rebuild the help files using the ‘Install and Restart’ button on the Build tab. Note, with the default Project Options, RStudio does not remake the documentation when you click ‘Install and Restart’. You have to change that by going to Tools > Project Options > Build Tools and then clicking ‘Configure’ next to ‘Generate documentation with Roxygen’ and then clicking the box next to ‘Install and Restart’. Or you can run this code to make the documentation.
devtools::document()The easiest way to figure out how to customize Roxygen headers is to look at the Roxygen header for a help file you are trying to copy. Or read the help file for details.
If you use BibTex you can insert references by citation in your help files.
inst folder if you don’t have oneREFERENCES.bib 3 Add refs to that in BibTex format.Imports in your DESCRIPTION file and add RdMacros: Rdpack to your DESCRIPTION file.\insertRef{Waltonetal1998}{MyNewPackage}Example of a reference in REFERENCES.bib
@article{Waltonetal1998,
title={The development and operational application of nonlinear algorithms for the measurement of sea surface temperatures with the NOAA polar-orbiting environmental satellites},
author={Walton, CC and Pichel, WG and Sapper, JF and May, DA},
journal={Journal of Geophysical Research: Oceans},
volume={103},
number={C12},
pages={27999--28012},
year={1998},
publisher={Wiley Online Library}
}Add the citation to your Rd file with
\insertRef{Waltonetal1998}{MyNewPackage}usethis::use_pkgdown()
pkgdown::build_site()Let’s get this up on GitHub using GitHub Pages. Go to Settings on your repo and scroll down to ‘GitHub Pages’.
I have created a template that you can clone:
Let’s walk through the pieces.