Introduction to 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:

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.

Basic usage

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

── docreview Results ───────────────────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✓ add
x deduct

── Vignettes ──

── Flesch Kincaid reading complexity scores: 
! testpkg.Rmd: 36.1
! testpkg2.Rmd: 33.73

── Length scores 
✓ testpkg.Rmd: 351 words.
✓ testpkg2.Rmd: 170 words.

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))

── docreview Results ───────────────────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✓ add
x deduct

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))

── docreview Results ───────────────────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✓ add
x deduct

── Vignettes ──

── Flesch Kincaid reading complexity scores: 
x testpkg.Rmd: 36.1
x testpkg2.Rmd: 33.73

── Length scores 
✓ testpkg.Rmd: 351 words.
✓ testpkg2.Rmd: 170 words.

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))

── docreview Results ───────────────────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✓ add
x deduct

── Vignettes ──

── Flesch Kincaid reading complexity scores: 
! testpkg.Rmd: 36.1
! testpkg2.Rmd: 33.73

── Length scores 
✓ testpkg.Rmd: 351 words.
✓ testpkg2.Rmd: 170 words.
Error: 
Failures found by docreview: 1