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:

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

── docreview results for testpkg ───────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✔ add
✖ deduct

── Vignettes ──

── Flesch Kincaid reading complexity scores 
! testpkg.Rmd: 41.53
! testpkg2.Rmd: 37.28

── Length scores 
✔ testpkg.Rmd: 382 words.
✔ testpkg2.Rmd: 182 words.

── Image alt text 
Total # images in testpkg.Rmd : 5
Total # images in testpkg.Rmd containing alt text: 2
✖ Image 1
✖ Image 2
✔ Image 3
✖ Image 4
✔ Image 5
Total # images in testpkg2.Rmd : 0

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 for testpkg ───────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✔ add
✖ 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 for testpkg ───────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✔ add
✖ deduct

── Vignettes ──

── Flesch Kincaid reading complexity scores 
! testpkg.Rmd: 41.53
✖ testpkg2.Rmd: 37.28

── Length scores 
! testpkg.Rmd: 382 words.
✖ testpkg2.Rmd: 182 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 for testpkg ───────────────────────────────────────────────

── Function Documentation ──

── Exported functions containing examples in their documentation:  
✔ add
✖ deduct

── Vignettes ──

── Flesch Kincaid reading complexity scores 
! testpkg.Rmd: 41.53
! testpkg2.Rmd: 37.28

── Length scores 
✔ testpkg.Rmd: 382 words.
✔ testpkg2.Rmd: 182 words.
Error in FALSE: 
Failures found by docreview: 1