In jr-packages/jrPackage: Jumping Rivers: Building an R Package

Vignettes

If you want to include more extensive examples or even just further documentation, then you should consider creating a vignette:

\begin{quote} a \textbf{vignette} is a small illustration placed at the beginning or end of a book or chapter.

\em \url{http://dictionary.reference.com/browse/vignette} \end{quote}

\noindent{We can view vignettes from other packages using the \texttt{vignette()} function}

r vignette(package = "knitr")

\noindent{or to view in your web browser}

r browseVignettes(package = "knitr")

Example: markdown vignettes

Vignettes are stored in the vignettes/ directory. The simplest vignette uses R-markdown and is formatted by the knitr package. To create a package vignette, we simply place the file in the vignettes/ directory.

\marginnote{The output style is \texttt{html_vignette}. This is more lightweight (in terms of file size) than the standard \texttt{html_document}}

\indent{For example, suppose we have a file \texttt{intro.Rmd} that contains the following text:}

\marginnote{The UTF-8 line specifies the file encod- ing.}

```r

---

title: "My very first vignette" author: "Colin Gillespie and Robin Lovelace" output: rmarkdown::html_vignette #nolint start vignette: > #nolint end %\VignetteIndexEntry{My very first vignette} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8}

---

## My first package

This is my first package vignette. I can include mathematics, such as $x^2$. R code is also nicely formatted and displayed. ```

```r
x = runif(10)
```

and plots

```r
plot(x)
```

1. The first few lines register knitr as the vignette engine and provide an entry for the list of vignettes.

2. We have used markdown to add simple styling\sidenote{See \url{http://goo.gl/y9FO5} and the RStudio markdown reference sheet for further commands.}. For example \texttt{first} becomes first and \texttt{\$x\textasciicircum 2\$} becomes $x^2$.

3. R code is executed in the ``` regions.

Tasks

1. Create a vignettes/ directory in your package.

2. Create an R markdown file

File -> New File -> R markdown

and save it in the vignettes/ directory.

1. Copy the markdown example above into your file and knit that file.

2. Add

Suggests: knitr VignetteBuilder: knitr

to the DESCRIPTION file\sidenote{Notice that \textbf{knitr} is only a \textbf{suggested} package, since it’s not essential.}. This will tell your package to build \newline{vignettes using \textbf{knitr}.}

1. Vignettes won’t actually be built unless you are creating a source bundle\sidenote{If you submit your package to CRAN, then the vignettes will be built ready for distribution.}. To install a package with vignettes included, we first create the source package Build -> Build Source Package \noindent{and then install the package from source} r install.packages("pkg_1.0.tar.gz", repos=NULL, type="source") \noindent{Build and install your package. Check that you can access the vignette.}

2. Check and ensure that your package passes all tests\sidenote{CTRL + E.}.

Package level documentation

You package typically also has documentation associated with the package name. For example,

r library("pkg") ?pkg

\noindent{should bring up an overview of your package. Again we use \textbf{roxygen2} to generate the man page. Go to}

\begin{center} \url{http://goo.gl/W2tJrF} \end{center} \noindent{to view the entry for the \textbf{poweRlaw} package.}

Tasks

1. Create a file called pkg-package.R in the R/ directory.

2. Using the poweRlaw package as an example, create a man/ page for your package\sidenote{What do you think the \texttt{@aliases} tag does?}.

3. Do one final check and ensure that your package passes all tests.

jr-packages/jrPackage documentation built on Dec. 4, 2020, 8:27 a.m.