13 Vignettes

13.1 Introduction

In addition to the manual documentation of the .Rd files, an R package can optionally contain another kind of supporting documentation known as vignettes. A vignette is basically a tutorial, intentionally designed to show users how to utilize the functions in the package. If you’ve never seen a vignette before, or are not sure if you’ve seen one, here’s an example of the introductory vignette in the package "dplyr":

https://cran.r-project.org/web/packages/dplyr/vignettes/dplyr.html

13.2 Including Vignettes

If you decide that your package needs one or more vignettes (which I strongly recommend), then you need to add a subdirectory called vignettes/. You can have as many vignettes as you consider convenient. Inside the vignettes/ subdirectory, you add either .Rmd (R markdown) files or .Rnw (R noweb) files. Since the markdown syntax is simpler than latex, I prefer to use .Rmd files to write the content of the vignettes.

Structure of vignette files

Figure 13.1: Structure of vignette files

When creating an .Rmd file for a vignette, you need to modify the yaml header with the following fields:

---
title: "Vignette Title"
author: "Vignette Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

Don’t forget to customize the values of the yaml fields:

  • title: the title of the vignette: e.g. “Introduction to Package cointoss”

  • author: who is the author(s) of the vignette

  • date: the default value will insert today’s date (but can choose a differnt date).

  • output: although there are various output formats available for .Rmd files, when used for vignettes you need to specify rmarkdown::html_vignette. This format has been specifically designed to work well inside packages.

  • vignette: this is the last yaml field which contains a special block of metadata needed by R. You only need to modify the \VignetteIndexEntry to provide the title of your vignette. The other two lines should not be changed. They tell R to use knitr to process the file, and that the file is encoded in UTF-8 (the only encoding you should ever use to write vignettes).

The following screenshot shows part of the contents in the introductory vignette for the working example package "cointoss". Notice that there is a code chunk with the library() function in order to load the package: e.g. library(cointos.

Screenshot of the vignette in cointoss

Figure 13.2: Screenshot of the vignette in cointoss

To know more about vignettes see r-pkgs: Package Vignettes.

Make a donation

If you find this resource useful, please consider making a one-time donation in any amount. Your support really matters.