Yet another post with a focus on package documentation! This time, we’ll cover vignettes a.k.a “long-form package documentation”, both basics around vignette building and infrastructure, and some tips for more maintainer- and user- friendliness.
What is a vignette? Where does it live?
Vignette 101 In the “R packages” book by Hadley Wickham and Jenny Bryan, the vignettes chapter starts with “A vignette is a long-form guide to your package. Function documentation is great if you know the name of the function you need, but it’s useless otherwise.” In “Writing R Extensions”, vignettes are defined as “documents in PDF or HTML format obtained from plain-text literate source files from which R knows how to extract R code and create output (in PDF/HTML or intermediate LaTeX).”.
As a package author you could be fine only knowing about usethis::use_vignette() for creating a vignette, and that packages used in the vignette need to be listed in DESCRIPTION (under Suggests if they’re only used in the vignette). Still, it’s useful to know about vignettes for debugging problems or finding workarounds for issues you might encounter.
The building of package vignettes can either use the default Sweave vignette engine, or a vignette engine provided by a CRAN package like knitr by Yihui Xie. knitr::rmarkdown vignette engine is the one recommended in the R packages book, and usethis. It allows writing vignettes in R Markdown. See the source of rhub main vignette. It has YAML metadata at the top, some non-executed code chunks, some executed code chunks. To allow for that vignette to be built, a field in DESCRIPTION mentions the vignette engine:
And these two packages are declared as dependencies under Suggests as well.
The creation of a boilerplate Rmd under a new vignettes folder, and the dependencies declaration in DESCRIPTION, are what usethis::use_vignette() would handle for you. Then you can write as you would a standard R Markdown document, knitting for previewing it. Other vignette builders include R.rsp that we’ll mention again later, noweb to use the noweb literate programming tool (which actually looks a lot like sweave?), rasciidocs that was recently archived at the time of writing. It is unlikely you’ll want to write your own vignette engine.
If your vignette shows an external image not generated by the build process, you also need to include it in install_extras, * During installation the content of inst/doc/ get copied to doc/. (See e.g. rhub content in my local library:)
Vignette metadata is important. A non place-holder title in VignetteIndexEntry is compulsory! Vignettes with a place-holder title are even called bad_vignettes in R source. 😱
Based on what we said in the previous subsection, R CMD build builds vignettes from vignettes/ whereas R CMD check checks they can be rebuilt from inst/doc/. So if there were data in vignettes/, given it’s not copied to inst/doc/… R CMD check will error!
It’s also useful to know that there are options related to vignette building and checking in R CMD build and R CMD check. Of course you don’t control these options for CRAN but you do control them when sending your packages to R-hub package builder, and when setting up continuous integration. See for instance this great tip by John Blischak, “checking the package while ignoring the vignettes can be done with the following steps:”