Package check and documentation

R package development workshop

Heather Turner and Ella Kaye

Department of Statistics

June 27, 2027

Overview

• Check your package!
• DESCRIPTION
• README
• Continuous Integration (CI)
• Vignettes
• NEWS
• Package website with pkgdown

Check your package!

R CMD check

R CMD check is the command line utility provided by R to check R packages.

It checks that all the components are valid and consistent with each other, in particular:

• Metadata in DESCRIPTION
• Imports and exports in NAMESPACE
• .Rd files in /man

It will also run any examples and tests you have written.

devtools::check() will run R CMD check in the background, with the results shown in the Build pane.

Note that this doesn’t check the correctness of code - this is the role of tests

Run devtools::check()

You will get lots of output. It will end with:

-- R CMD check results ---------- animalsounds 0.0.0.9000 ----
Duration: 9.3s

> checking DESCRIPTION meta-information ... WARNING
  Non-standard license specification:
    `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license
  Standardizable: FALSE

0 errors √ | 1 warnings x | 0 notes √

We haven’t yet specified a license for our package.

On running check() you may get an error if you are using a networked drive. There’s a fix coming in a few slides.

Aside: in case of error

On running devtools::check() you may get an error of the form

Updating animalsounds documentation  
Error: The specified file is not readable: path-to\animalsounds\NAMESPACE  

This can happen if your repo is on a networked drive.

This is covered in this Stackoverflow question and can be fixed.

Aside: a fix for networked drives

1. Save a copy of this file: fix_for_networked_drives.R

   Save it somewhere other than the animalsounds directory

2. Open the file from the animalsounds project session

3. Run the whole file

You should now find that devtools::check() proceeds normally.

Types of problem

ERROR	Must fix to get the code/example/test working
WARNING	Fix if sharing with others
NOTE	Fix if submitting to CRAN

It is possible to submit to CRAN with a NOTE, but it’s best avoided.

NOTES best avoid for CRAN as they require a person to respond. One unavoidable case of a NOTE on CRAN submission: first submission of a package

Check regularly, fix issues as they arise

Will see later in this session how to do this automatically with Continuous Integration

DESCRIPTION

The are two types of documentation: package level and function level.

The DESCRIPTION file provides some of the package level documentation (or metadata)

Metadata in DESCRIPTION

• Package: The package name. The changer package can help you change the name!
• Title: One line, title case, with no period. Fewer than 65 characters.
• Version
  • for release: MAJOR.MINOR.PATCH version.
  • for development version building on version MAJOR.MINOR.PATCH, use: MAJOR.MINOR.PATCH.9000
  • can be filled in with usethis::use_version()

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards compatible manner, and PATCH version when you make backwards compatible bug fixes.

Will see usethis::use_version() in session on publication

Metadata in DESCRIPTION

• Authors@R: A call to person() that is run to create the Author field when the package tarball is built. “aut” means author, “cre” means creator (maintainer), “ctb” means contributor.

  A placeholder call to person() is inserted in DESCRIPTION when a package is created with usethis::create_package() which can be edited directly:

  person("A", "Person", email = "a.person@email.com", 
         role = c("aut", "cre"),
         comment = c(ORCID = "0000-0001-2345-6789"))

  Alternatively, this can be overwritten with a call to usethis::use_author():

  use_author("A", "Person", email = "a.person@email.com", 
       role = c("aut", "cre"),
       comment = c(ORCID = "0000-0001-2345-6789"))

usethis::use_author() is new in usethis 2.2.0

Metadata in DESCRIPTION

• Description: One paragraph describing what the package does. Keep the width of the paragraph to 80 characters; indent subsequent lines with 4 spaces.
• License: Will discuss later
• Encoding: How to encode text, use UTF-8 encoding.
• LazyData: If true data sets in the package are stored in a database during package installation and loaded from the database as required. Recommended if shipping data with package – usethis::use_data() will set this for you.

usethis::create_package() sets UTF-8 encoding

lazy loading means that data is only loaded if needed. This means that they won’t occupy any memory until you use them. do NOT include LazyData: true in DESCRIPTION unless you actually ship data in your package.

Open source licenses

There are three main open source licenses:

• CC0: “public domain”, best for data packages.

  usethis::use_cc0_license()

• MIT: Free for anyone to do anything with (including bundling in closed source product).

  usethis::use_mit_license()

• GPL: Changes and bundles must also be GPL

  usethis::use_gpl_license()

  If you are including someone else’s GPL code directly, you must use GPL yourself.

https://bookdown.org/rdpeng/RProgDA/open-source-licensing.html

somewhat personal down to how important you consider open source to be and what you are happy with people doing with your code

Suggest academic: GPL; community/other: MIT

Proprietary packages

You can use usethis::use_proprietary() to make it clear that your package isn’t open source.

usethis::use_proprietary(copyright_holder = "ACME Ltd")

In DESCRIPTION:

License: file LICENSE

In LICENSE:

Copyright 2023 ACME Ltd. All rights reserved.

Licensing considerations at universities

This slide is specific for The University of Warwick, but similar considerations are likely to be true at other Universities.

• Software is defined as a creative output (unlike scholarly works, e.g. thesis, conference paper)

• The university owns the IP of any software created by Warwick PhD students and staff in the course of their work

• Before making code public or publishing software under any license, contact Brendan at B.Spillane@warwick.ac.uk

  • Permission to publish under an open source license likely to be granted for research code
  • Not necessary to obtain permission if open source software was part of grant proposal (as proposal will have already been checked by Research & Impact Services, who will have identified any IP issues).

Extra note from Brendan: “they don’t need to come to me with every single bit of code they open source. I’m more interested in the entirety of the project rather than approving 2000 bits of individual code!”

Your turn

1. Open the DESCRIPTION file and add a title and description.
2. Add yourself as an author and creator.
3. Add an MIT license.
4. Run the package check.
5. Commit changes to GitHub.

Tip

In RStudio, you can use the ‘Go to file/function’ box or Ctrl + . [period] and start typing a file name to open a file for editing.

README

README

The README is the quick start guide to your package.

It should include

• a brief overview
• instructions on how to install the package
• a few examples

You should be able to borrow from the DESCRIPTION and help files!

It’s readable on the package’s GitHub repo and on the homepage of its website (more on that later).

Creating a README

usethis has functions to set up a README with/without R code

usethis::use_readme_rmd()
usethis::use_readme_md()

README.Rmd must be rendered to make README.md each time it is changed.

usethis::use_readme_rmd() creates a pre-commit hook to check if README.Rmd and README.md are out of sync before committing.

Use build_readme() to render with the latest version of the code.

build_readme creates a temporary version of the package

Continuous Integration (CI)

The practice of merging new code into the repository and running checks each time is known as Continuous Integration.

Running automatic checks

GitHub Actions (GHAs) allow you to run code every time you push to GitHub.

The most useful ones for packages can be selected from a call to usethis::use_github_action():

use_github_action()

Which action do you want to add? (0 to exit)
(See <https://github.com/r-lib/actions/tree/v2/examples> for other options) 

1: check-standard: Run `R CMD check` on Linux, macOS, and Windows
2: test-coverage: Compute test coverage and report to https://about.codecov.io
3: pr-commands: Add /document and /style commands for pull requests

check-standard sets up a GHA that runs R CMD check with the latest release of R on Linux, Mac, and Windows and with both the previous release and development release of R on Linux.

This behaviour of use_github_action() is new in usethis 2.2.

use_github_actions() is deprecated.

use_github_action("check-release")

The check-standard GHA is best-practice for ‘serious’ projects, e.g. those aiming for CRAN, but is overkill for our purposes.

We can set up a simpler GHA by specifying an alternative:

use_github_action("check-release")

This sets up a bare-minimum workflow that runs R CMD check with the latest release of R on Linux.

It’s good for simple package with no OS-sepcific code, and if you want a quick start with R CI.

i.e. it’s perfect for us!

Reminder to fix any issues as soon as they arise!

Your turn

1. Create a README for animalsounds with usethis::use_readme_rmd().
2. Fill in the description and an example.
3. Try adding the README in a git commit – it should fail! Render the README with build_readme(), then add both README.Rmd and README.md in a git commit.
4. Run usethis::use_github_action("check-release"). It adds a badge to the README, so you will need to render the README again.
5. Commit all the changes to git.

Vignettes

Vignettes

Vignettes are long-form documentation for your package.

They use R markdown to integrate code and output into the documentation. Typically:

• A single/main vignette showing a complete workflow.
• Optional further vignette(s) going deeper on one aspect/application
• Optional further vignette(s) for specialist audience (methodologists or developers)

A vignette with the same name as the package (e.g., vignettes/animalsounds.Rmd or vignettes/articles/animalsounds.Rmd) automatically becomes a top-level “Get started” link.

Fairly short read ~10 minutes

use_vignette()

Easiest way to get started is with usethis::use_vignette()

usethis::use_vignette("name")

Adds to DESCRIPTION

Suggests: knitr
VignetteBuilder: knitr

Creates vignettes/

Drafts vignettes/name.Rmd

use_vignette() will fill both title fields with the “name” of the file, but you’ll want to edit to something more descriptive.

Needs to be .Rmd not .qmd. Quarto is not R-specific and CRAN can’t publish .qmd files.

Vignette = Rmarkdown + special metadata

---
title: "Vignette Title"
author: "Vignette author"
date: "2024-06-13"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---

• html_vignette output uses a custom style sheet to keep the file size of the HTML as small as possible.
• The vignette: field contains special metadata needed when the package is built. Don’t forget to change the title here too!

Vignette workflow

Need to install package so can call with library()

Articles

Vignette code needs to be able to run on CRAN. There are some cases where this is not possible.

As an alternative, you can use articles instead of vignettes:

usethis::use_article("my-article")

✔ Adding 'rmarkdown' to Config/Needs/website
✔ Creating 'vignettes/'
✔ Creating 'vignettes/articles/'
✔ Adding '*.html', '*.R' to 'vignettes/.gitignore'
✔ Writing 'vignettes/articles/my-article.Rmd'
• Modify 'vignettes/articles/my-article.Rmd'
✔ Adding '^vignettes/articles$' to '.Rbuildignore'

Your turn

1. Install your animalsounds package and restart R (Install button).
2. Create a simple vignette, animalsounds, that shows how to use animal_sounds().
3. Fix the “vignette title” in the YAML header.
4. Knit the vignette to preview it.
5. Run devtools::install(build_vignettes = TRUE) to install the package with the vignettes. Call browseVignettes("animalsounds") to open your vignette.
6. Commit your changes to git.

NEWS

Track changes in a NEWS file

usethis::use_news_md()

Add news for the latest version at the top.

Use a top-level heading for each release version

# animalsounds 1.0.0

What news to include

Add each change in a bulleted list:

• If you have many changes, split into subsections (e.g. ## Major changes, ## Minor improvements, ## Bug fixes).
• Wait until release to decide if subsections are necessary

Note connections to GitHub:

• If related to a GitHub issue, add the issue number, e.g. (#10).
• If related to a pull request, add the pull request number and the author, e.g. (#101, @hadley).

Package website with pkgdown

A package website pkgdown

The pkgdown package is designed to make it quick and easy to build a website for your package:

usethis::use_pkgdown()

Why have a website for your package?

• Google-ability
• Easy-to-read and browse documentation and package information in one place
• Examples with output!

Build a website

pkgdown::build_site() creates a package website based on the standard documentation files.

Home page: based on README

Reference:

• one page for each help file
• generates an index page, with functions listed alphabetically by default

For packages with lots of functions, it’s good to organise them by theme or functionality.

Build a website (ctd)

Articles: one page for each vignette

Get Started: if you have a vignette with filename = package name

News: based on NEWS.md

Plus:

• A link to your GitHub repo (if listed in the DESCRIPTION url field).
• A link to the License
• Any badges added to your README (e.g. from GitHub Actions)

Hosting your website

• You can host your website directly from its GitHub repo (repo has to be public)

• The recommended approach is to let GitHub build your page (instead of calling pkgdown::build_site() and committing and pushing the artifacts of the built website (i.e., html files) to GitHub

• Add an action to your GitHub repo to be run automatically every time you push to it to rebuild the site:

  usethis::use_pkgdown_github_pages()

• The URL will be https://USERNAME.github.io/animalsounds

use_pkgdown_github_pages() will:

• call use_pkgdown() - allow it to overwrite existing _pkgdown.yml (will add the url)
• set up a gh-pages branch from which to deploy the site
• add a pkgdown.yml to .github/workflows

Will still need to call pkgdown::build_site() to preview locally

Customising your website

You can add more information to _pkgdown.yml to customise the package website:

• curate the index for the Reference page - functions can be grouped and described in categories

  https://pkgdown.r-lib.org/articles/pkgdown.html#reference

• customise the appearance

  https://pkgdown.r-lib.org/articles/customise.html

Your turn

1. Run usethis::use_pkgdown_github_pages() – this will ask you to install pkgdown if you don’t already have it.
2. Read through all the output in the console to see the many things that this function does.
3. Look at the diffs in the Git pane. Commit and push all changes.
4. Go to your GitHub repo of the package. Click on Actions. If there’s a green tick next to “pages build and deployment” then your site is ready to view!
5. Click on the link to the website under the About section of the repo.
6. (Bonus) Change the appearance of the site with a Bootswatch theme: https://pkgdown.r-lib.org/articles/customise.html#bootswatch-themes.

End matter

References

Wickham, H and Bryan, J, R Packages (2nd edn, in progress), https://r-pkgs.org.

R Core Team, Writing R Extensions, https://cran.r-project.org/doc/manuals/r-release/R-exts.html

License

Licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).