Sunday, December 8, 2019 From rOpenSci (https://ropensci.org/blog/2019/12/08/precompute-vignettes/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
As of earlier this year, we are now automatically building binaries and pkgdown documentation for all rOpenSci packages. One issue we encountered is that some packages include vignettes that require some special tools/data/credentials, which are unavailable on generic build servers.
This post explains how to include such vignettes and articles in your package.
By default, R automatically recreates vignettes during
R CMD check or when generating pkgdown sites by running all R code. This is useful because it provides some extra testing of your code and ensures that documentation is reproducible. However, sometimes it is not a good idea to run the code on every build server, every time. For example:
In such cases it is better to execute the rmarkdown code locally, and ship a vignette in the package which already contains the rendered R output.
Suppose you have a vignette called
longexample.Rmd. To pre-compute the vignette, rename the input file to something that is not recognized by R as rmarkdown such as:
longexample.Rmd.orig. Then run knitr in the package directory to execute and replace R code in the rmarkdown:
# Execute the code from the vignette knitr::knit("vignettes/longexample.Rmd.orig", output = "vignettes/longexample.Rmd")
The new output file
longexample.Rmd now contains markdown with the already executed R output. So it can be treated as a regular vignette, but R can convert it to html instantaneously without having to re-run R code from the rmarkdown.
The jsonlite package shows a real world example. In this case I pre-computed vignettes that access web APIs to prevent services from getting hammered (and potentially banning the check servers).
One gotcha with this trick is that if the vignette output includes figures, you need to store the images in the vignettes folder. It is also a good idea to explicitly name your rmarkdown knitr chunks, so that the images have sensible filenames.
Our recently onboarded package eia by Matt Leonawicz is a good example. This package provides an R client for US Energy Information Administration Open Data API. The eia documentation gets automatically generated for each commit on the rOpenSci docs server, even though the code in the vignettes actually requires an API key (which the docs server does not have).
The eia vignettes directory contains the
Rmd.orig input files and the
.Rmd files as pre-computed by the package author. Also note the vignettes directory contains a handy script precompile.R that makes it easy for the package author to refresh the output vignettes locally.
The drawback of this approach is that documents no longer automatically update when the package changes. Therefore you should only pre-compute the vignettes and articles that are problematic, and make a note for yourself to re-knit the vignette occasionally, e.g. before a package release. Adding a script to your vignette folders that does so can be a helpful reminder.