17.11 How vignettes are built and checked

• It can be helpful to appreciate the big difference between the workflow for function documentation and vignettes. The source of function documentation is stored in roxygen comments in .R files below R/. We use devtools::document() to generate .Rd files below man/. These man/*.Rd files are part of the source package. The official R machinery cares only about the .Rd files.

• Vignettes are very different because the .Rmd source is considered part of the source package and the official machinery (R CMD build and check) interacts with vignette source and built vignettes in many ways. The result is that the vignette workflow feels more constrained, since the official tooling basically treats vignettes somewhat like tests, instead of documentation.