How to precompute package vignettes or pkgdown articles

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: https://ropensci.org/technotes/2019/12/08/precompute-vignettes/

2 Likes

Thanks for the article, @jeroenooms. Iā€™ve already done this with GSODR and nasapower and have an updated version of the bomrang vignette waiting for the next release.

Itā€™s a super-handy way to handle internet connectivity and/or long execution times in vignettes.

1 Like

Interesting idea. I use a similar approach:
Pre-compute a model and save the output object (e.g., out, saved in out.rdata or so), then in markdown display the original code, but donā€™t run it (eval=F,include=T), and in actuality load the ā€˜out.rdataā€™ file, but donā€™t display it (eval=T,echo=F).
The problem with that is that if itā€™s MCMC draws, the out.rdata file takes up a lot of space, and you donā€™t really want to upload that to github or bitbucket.

Nice article @jeroenooms, it is maybe worth mentioning to clean up and add the precompile.R and the *.Rmd.orig files to .Rbuildignore.

Thanks @jeroenooms for a nice article, a small addition - you can also run purl next to knit to have the vignetteā€™s R code accessible to the users, like in a ā€œnormalā€ vignette:

knitr::purl("vignettes/longexample.Rmd.orig", output = "vignettes/longexample.R")

I think some clarification is needed about the last part, saving vignette figures.

With this method, it does not work to set knitr::opt_chunks$set(fig.path = "vignettes/"), or to use the default fig.path setting of "figure/". Based on the example repo, I used knitr::opt_chunks$set(fig.path = "vigfig-") in the vignette Rmds so that all figures got saved to the root project (package) directory with vigfig- appended to the front of the file name, then moved them into vignettes with fs::file_move():

# Move figures into vignettes/ folder
figs <- list.files(pattern = "vigfig-")
fs::file_move(figs, fs::path("vignettes/", figs))