8 Other documentation

In a previous section we documented our functions using Roxygen comments but there are a few other kinds of documentation we should have.

8.1 Package help file

Users can find out about our functions using ?function-name but what if they want to find out about the package itself? There is some information in the DESCRIPTION but that can be hard to access. Let’s add a help file for the pacakge.

✔ Writing 'R/mypkg-package.R'

This creates a special R file for us called mypkg-package.R. The contents of this file doesn’t look like much it is understood by devtools and roxygen2.

Run devtools::document().

Updating mypkg documentation
Writing NAMESPACE
Loading mypkg
Writing NAMESPACE
Writing mypkg-package.Rd

We can see that a new .Rd file has been created and we can view the contents using ?mypkg. The information here has been automatically pulled from the DESCRIPTION file so we only need to update it in one place.

8.2 Vignettes

The documentation we have written so far explains how individual functions work in detail but it doesn’t show what the package does as a whole. Vignettes are short tutorials that explain what the package is designed for and how different functions can be used together. There are different ways to write vignettes but usually they are R Markdown files. We can create a vignette with usethis::use_vignette(). There can be multiple vignettes but it is common practice to start with one that introduces the whole package.

What is R Markdown?

Markdown is a simple markup language that makes it possible to write documents with minimal formatting. See Help > Markdown Quick Reference in RStudio for a quick guide to how this formatting works. R Markdown adds chunks of R code that are run and the output included in the final document.

✔ Adding 'knitr' to Suggests field in DESCRIPTION
✔ Setting VignetteBuilder field in DESCRIPTION to 'knitr'
✔ Adding 'inst/doc' to '.gitignore'
✔ Creating 'vignettes/'
✔ Adding '*.html', '*.R' to 'vignettes/.gitignore'
✔ Adding 'rmarkdown' to Suggests field in DESCRIPTION
✔ Writing 'vignettes/mypkg.Rmd'
● Modify 'vignettes/mypkg.Rmd'

Because this is our first vignette usethis has added some information to the DESCRIPTION file including adding the knitr package as a suggested dependency. It also creates a vignettes/ directory and opens our new mypkg.Rmd file.

---
title: "mypkg"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{mypkg}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE} 
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup} 
library(mypkg)
```

If you are familiar with R Markdown you might note some unusual content in the header. This is important for the vignette to build properly. There are also some knitr options set which are the convention for vignettes.

Let’s add a short example of how to use our package.

---
title: "mypkg"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{mypkg}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE} 
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup} 
library(mypkg)
```

# Introduction

This is my personal package. It contains some handy functions that I find useful
for my projects.

# Colours

Sometimes you want to generate shades of a colour. The `make_shades()` function
makes this easy!

```{r} 
shades <- make_shades("goldenrod", 5)
```

If you want to see what the shades look like you can plot them using
`plot_colours()`.

```{r} 
plot_colours(shades)
```

This function is also useful for viewing any other palettes.

```{r} 
plot_colours(rainbow(5))
```

To see what the vignette looks like run devtools::build_vignettes(). Asking devtools to build the vignette rather than rendering it in another way (such as the Knit button in RStudio) makes sure that we are using the development version of the package rather than any version that is installed.

Building mypkg vignettes
--- re-building 'mypkg.Rmd' using rmarkdown
--- finished re-building 'mypkg.Rmd'

Moving mypkg.html, mypkg.R to doc/
Copying mypkg.Rmd to doc/
Building vignette index

This creates a new directory called doc/ that contains the rendered vignette. Click on the mypkg.html file and open it in your browser.

If you want to use any other packages in your vignette that the package doesn’t already depend on you need to add them as a suggested dependency.

8.3 README

If you plan on sharing the source code rather than the built package it is useful to have a README file to explain what the package is, how to install and use it, how to contribute etc. We can create a template with usethis::use_readme_md() (if we wanted to and R Markdown file with R code and output we might use usethis::use_readme_md() instead).

✔ Writing 'README.md'
● Modify 'README.md'
# mypkg

<!-- badges: start -->
<!-- badges: end -->

The goal of mypkg is to ...

## Installation

You can install the released version of mypkg from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("mypkg")
```

## Example

This is a basic example which shows you how to solve a common problem:

``` r
library(mypkg)
## basic example code
```

There are the comments near the top that mention badges and you might have seen badges (or shields) on README files in code repositories before. There are several usethis functions for adding badges. For example we can mark this package as been at the experimental stage using usethis::use_lifecycle_badge().

# mypkg

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
<!-- badges: end -->

The goal of mypkg is to ...

The rest of the template isn’t very useful so replace it with something better.

8.4 Package website

If you have a publicly available package it can be useful to have a website displaying the package documentation. It gives your users somewhere to go and helps your package appear in search results. Luckily this is easily achieved using the pkgdown package. If you have it installed you can set it up with usethis.