R package toolchain#

To document R packages, we use a toolchain that includes RStudio, GitHub actions, and gh-pages. Even though the process involves different tools, it follows the same “docs as code” philosophy as the primary Sphinx/Read the Docs toolchain.

Install R packages#

In addition to installing the R package you want to document and its dependencies in RStudio, you must install knitr and roxygen2.

  1. In Rstudio, go to the Tools menu and select Install Packages.

  2. In the installation menu, enter “knitr, roxygen2” in the Packages text box.

  3. Click Install.

Write documentation#

API reference#

Similar to how the autodoc plug-in for Sphinx automatically produces API reference documentation from Python docstrings, the roxygen2 package automatically produces API reference documentation from R comments. Roxygen2 generates .Rd files in the man/ directory which are then compiled into HTML documentation.

For more information, see https://roxygen2.r-lib.org/articles/roxygen2.html.

Conceptual/procedural docs#

All other documentation for R packages is written in what are known as “vignettes.” These are R Markdown (.rmd) files placed in a vignettes folder within the R package. The vignette with the same name as the package is treated as the primary conceptual documentation for the package and is automatically given the title “Get started”. You may have more than one vignette: each additional vignette will be listed alphabetically (by filename) under “Articles”.

_images/vignettes.png

Because the compiled HTML is not assembled with a TOC for navigation and you cannot assemble multiple vignettes into a hierarchical structure, we recommend including all information necessary for the routine usage of the R package in the primary vignette. Supplementary or optional information should be placed in one or more additional vignettes.

Test the build#

API reference#

Enter either of the following commands to run roxygen2:

roxygen2::roxygenise().

devtools::document().

Alternatively, press Ctrl + Shift + D if you are using RStudio.

Conceptual/procedural docs#

While you may use any text editor you like to write the vignettes, we recommend testing the vignette build within RStudio. You can either click Knit periodically, or select the Knit on Save checkbox.

_images/knitr.png

Automatic builds and hosting#

The final piece of the R documentation toolchain is GitHub. Use GitHub actions to rebuild the documentation upon each code change and then push the compiled HTML to gh-pages for hosting. For more information, see https://support.github.com/features/actions and https://pages.github.com/.

It’s important to note that gh-pages has some limitations compared to Read the Docs. Documentation hosted on gh-pages cannot be made private and will be publicly available, even for private GitHub repos. Additionally, gh-pages cannot easily host multiple versions of the documentation. While Read the Docs has some nice server-side search functionality, gh-pages uses the client-side search provided by the documentation generator; in the case of R documentation with roxygen2 and knitr, there is no search.