17.12 R CMD build and vignettes

First, it’s important to realize that the vignettes/*.Rmd source files exist only when a package is in source (Section 4.3) or bundled form (Section 4.4). Vignettes are rendered when a source package is converted to a bundle via R CMD build or a convenience wrapper such as devtools::build(). The rendered products (.html) are placed in inst/doc/, along with their source (.Rmd) and extracted R code (.R; discussed in Section 18.6.2). Finally, when a package binary is made (Section 4.5), the inst/doc/ directory is promoted to a top-level doc/ directory, as happens with everything below inst/.

The key takeaway from the above is that it is awkward to keep rendered vignettes in a source package and this has implications for the vignette development workflow. It is tempting to fight this (and many have tried), but based on years of experience and discussion, the devtools philosophy is to accept this reality.

Assuming that you don’t try to keep built vignettes around persistently in your source package, here are our recommendations for various scenarios:

  • Active, iterative work on your vignettes: Use your usual interactive .Rmd workflow (such as the button) or devtools::build_rmd(“vignettes/my-vignette.Rmd”) to render a vignette to .html in the vignettes/ directory. Regard the .html as a disposable preview. (If you initiate vignettes with use_vignette(), this .html will already be gitignored.)

  • Make the current state of vignettes in a development version available to the world:

    • Offer a pkgdown website, preferably with automated “build and deploy”, such as using GitHub Actions to deploy to GitHub Pages. Here are tidyr’s vignettes in the development version (note the “dev” in the URL): https://tidyr.tidyverse.org/dev/articles/index.html.

    • Be aware that anyone who installs directly from GitHub will need to explicitly request vignettes, e.g. with devtools::install_github(dependencies = TRUE, build_vignettes = TRUE).

  • Make the current state of vignettes in a development version available locally:

    • Install your package locally and request that vignettes be built and installed, e.g. with devtools::install(dependencies = TRUE, build_vignettes = TRUE).

  • Prepare built vignettes for a CRAN submission: Don’t try to do this by hand or in advance. Allow vignette (re-)building to happen as part of devtools::submit_cran() or devtools::release(), both of which build the package.

  • If we really do want to build vignettes in the official manner on an ad hoc basis, devtools::build_vignettes() will do this. But we’ve seen this lead to developer frustration, because it leaves the package in a peculiar form that is a mishmash of a source package and an unpacked package bundle.

  • This nonstandard situation can then lead to even more confusion. For example, it’s not clear how these not-actually-installed vignettes are meant to be accessed. Most developers should avoid using build_vignettes() and, instead, pick one of the approaches outlined above.