In thisisnic/docreview: Opinionated Documentation Checking

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "",
  prompt = TRUE
)

library(docreview)

When writing R packages, high quality documentation can make for a great experience for your users.

You can use docreview to check that your R package documentation passes a number of checks:

• all exported functions should have documented examples of how to use them
• vignettes should not be too long
• vignettes should not be too short
• vignettes should not be too complex

This list of checks, as well as the metrics used to assess them, is likely to grow as docreview changes over time, until stabilising after the version 1.0.0 release.

You can use docreview to check your documentation locally, and also on your CI - see below for how to raise an error when a documentation review check fails.

Note that some vignette checks require you to have compiled the HTML versions. You can use tools::buildVignettes() to do this.

# ensure you have rebuilt your vignettes if you want to run checks requiring the HTML files
tools::buildVignettes(dir = "./path_to_package/")

Basic usage

library(docreview)
pkg_path <- system.file("testpkg", package = "docreview")
package_review(path = pkg_path)

Choose what to review

You can choose which components of documentation to review.

func_only_config <- system.file("configs/just_functions.yml", package = "docreview")
package_review(path = pkg_path, config = get_config(func_only_config))

Set custom thresholds for review check failures and warnings

You might not agree with the thresholds set for review checks resulting in failures or warnings. That's OK! You can set your own custom thresholds.

stricter_thresholds <- system.file("configs/thresholds.yml", package = "docreview")
package_review(path = pkg_path, config = get_config(stricter_thresholds))

Raise an error when review checks produce failures or warnings

If you're using docreview as part of your CI, you may want to raise an error when the review checks produce a failure or warning.

error <- system.file("configs/error.yml", package = "docreview")
docreview::package_review(path = pkg_path, get_config(error))

thisisnic/docreview documentation built on Feb. 20, 2024, 1:53 p.m.