Skip to contents

Updating Documentation

Source: vignettes/dev-update-documentation.Rmd
dev-update-documentation.Rmd

This document describes how to update the documentation that supports the package, including R help pages, dataset documentation, articles, app help materials, and the pkgdown website.

Updating package documentation

The R package is documented in web pages and in standard R help files viewable in RStudio. Documentation generally needs to be updated before a new package release. Updates may be needed in the following places:

  1. Package: overall package-wide information and documents

  2. Functions: reference docs explaining the R functions

  3. Datasets: reference docs explaining the datasets (in EJAM/R/data_*.R files)

  4. Articles: vignettes helping R users with the package (in EJAM/vignettes/*.Rmd)

  5. User Guide: help for people using the web app (in EJAM/inst/app/www/ as a PDF file)

  6. Spell-checking package-wide

  7. Website: web pages providing all of the above in HTML format, via the pkgdown package

Each is explained below:

Package: overall package-wide information and documents

  • Package-wide documentation files can be edited directly and include the following: DESCRIPTION, README.Rmd (for the README, edit README.Rmd, not the generated README.md file), R/EJAM-package.R (for ?EJAM-package), NEWS.md used to make NEWS, CONTRIBUTING.md used to make CONTRIBUTING, LICENSE based on inst/LICENSE.md, CITATION based on inst/CITATION, CITATION.cff, and others.

  • Some of these are used by and shown by the GitHub repository, notably the README.md that is generated from the README.Rmd file and appears on the GitHub repository as README and in the pkgdown site as README, and the DESCRIPTION file that stores the package version number, repository URLs, and related package metadata.

Functions: reference docs explaining the R functions

  • roxygen2 package tags define the documentation in the R/*.R files that contain the source code and documentation of functions and datasets.

  • While many functions or objects have their own .R files, some .R files contain code and documentation for multiple functions, so not every function has a file of its own.

  • Some utility/helper functions, mostly not exported, are stored in files prefixed with utils_, such as R/utils_indexblocks.R documenting indexblocks() (but not all helper functions are in files named that way).

  • It can be useful to check generated help files with tools::checkDocFiles(".") after running roxygen2::roxygenise().

Datasets: reference docs explaining the datasets

  • All datasets are documented in files named with a prefix of data_, such as R/data_blockgroupstats.R which documents the ?blockgroupstats dataset.

  • Most dataset documentation is created or updated alongside the code that creates or updates those datasets. For annual EJScreen-style datasets, use the staged pipeline described in Updating EJScreen Datasets Annually (via the Pipeline). For other package datasets, see Updating and Managing the Datasets Used by EJAM and the relevant data-raw/datacreate_*.R scripts.

  • Many R/*.R files for datasets are created automatically, not edited by hand, through the dataset_documenter() function as used in the scripts within data-raw/datacreate_*.R, while others are updated by editing the .R file directly.

Articles: vignettes helping R users with the package

  • Articles (called vignettes here) are written and edited as .Rmd files in the vignettes folder. Edit the .Rmd source file, not the generated HTML article.

  • Preview one article after editing it, before rebuilding the whole site:

EJAM:::pkgdown_preview_article("installing")
EJAM:::pkgdown_preview_article("vignettes/dev-update-documentation.Rmd")

These preview helpers build into a temporary folder by default, so they do not publish anything and do not require committing generated HTML. They also try to use the Pandoc bundled with RStudio if a terminal R session cannot find Pandoc on its own.

  • New articles or renamed files also require edits to _pkgdown.yml.

User Guide: help for people using the web app

  • If you change the UI, new screenshots may be needed for a new version of the User Guide. The User Guide has historically been stored as a PDF document built from a Word document.

Spell-checking package-wide

  • To run a spell check and review terms flagged as possible problems:
    x <- spelling::spell_check_package()
    x <- data.frame(
      frq = sapply(x$found, function(z) {length(unlist(z))}), 
      word = x$word)
    x <- x[order(x$frq), ]
    rownames(x) <- NULL
    x

  • Then use Ctrl-Shift-F to search all files for a flagged term and check whether it is actually a problem.

  • To update inst/WORDLIST, the list of words ignored by spell checking:

    # 1. Add obvious dataset names documented to the WORDLIST
    datanames = gsub('\\.R$', '', gsub('^data_', '', dir('./R', pattern = '^data_.*R')))
    datanames = datanames[!grepl('aaaaaaaaaaaaa|xxxxxxxxxx', datanames)]
    # 2. Add names of functions to the WORDLIST
    funcnames = EJAM:::pkg_functions_and_data( 'EJAM' )$object
    wordlist = readLines('inst/WORDLIST')
    wordlist = sort(unique(union(wordlist, c(datanames, funcnames))))
    # Write the revised list of words to the file
    writeLines(wordlist, 'inst/WORDLIST')

Website: web pages providing all of the above in HTML format

The web-based documentation pages are built from source files by pkgdown and published by GitHub Actions. The public site should be served from the root of the gh-pages branch. Source branches such as main, development, and release branches should not publish from main/docs and should not commit generated docs/ HTML.

In normal documentation work, edit and commit source files such as .R, .Rmd, README.Rmd, NEWS.md, DESCRIPTION, man/*.Rd inputs generated from roxygen comments, and _pkgdown.yml. Do not edit docs/ or the gh-pages branch by hand; those are generated deployment outputs.

Normal workflow for a vignette edit

  1. Edit the relevant .Rmd file in vignettes/.

  2. Preview just that article:

EJAM:::pkgdown_preview_article("installing")

  1. If the article is new, renamed, removed, or moved in the navigation, update _pkgdown.yml.

  2. Commit and push the source files only. Do not add generated docs/ files.

  3. Let GitHub Actions build and publish the public site after the source branch is pushed or merged into the branch that controls the desired documentation version.

  • The first step in updating those web pages is updating the YAML file. The web-based documentation pages are organized by a file called _pkgdown.yml – see usethis::edit_pkgdown_config() – which specifies the contents of the documentation web pages, such as the names of any vignette files to be shown in the list of articles, which functions are included in the reference pages index, and related settings. Any new, removed, or renamed functions, vignettes, datasets, or changes in what is exported may require edits to _pkgdown.yml.

  • For local checks, EJAM:::pkgdown_update() is still available as a maintainer utility. Treat it as a local preview/check workflow, not the publishing workflow. It can still be useful when you want broader local checks around roxygen documentation, README rendering, pkgdown site structure, or stale .Rd files.

  • For a faster local site preview without publishing:

EJAM:::pkgdown_preview_site()
EJAM:::pkgdown_preview_site(pkgdown_dev_mode = "devel")

  • Public publishing is handled by .github/workflows/pkgdown.yaml. GitHub Pages should be configured to publish from the root of the gh-pages branch. The workflow builds the site in a runner and deploys generated HTML to gh-pages.

  • The normal publishing paths are:

    • main builds the current release documentation at the site root.
    • development builds development documentation under dev/.
    • version tags and GitHub releases build historical documentation under the tag name, such as v3/.
    • manual workflow dispatch can build a chosen ref into a chosen folder.

  • The workflow file must exist on the branch that GitHub Actions uses for the event being triggered. For normal public updates, make sure the workflow change has reached the default branch before expecting future main pushes to rebuild the root documentation site.

  • To publish historical docs for an older release, use a tag or release such as v3 and deploy it to the same folder name. The resulting URLs should look like:

https://public-environmental-data-partners.github.io/EJAM/
https://public-environmental-data-partners.github.io/EJAM/dev/
https://public-environmental-data-partners.github.io/EJAM/v3/

  • The documentation is created and updated using the roxygen2 and pkgdown R packages, which read information from the .R files in the R folder, from .Rmd file vignettes (also called articles) in the vignettes folder, and from _pkgdown.yml. roxygen2 creates .Rd files in man/; pkgdown creates HTML files for GitHub Pages.

  • The URL where documentation is published at any given time should be recorded in the URL field of the DESCRIPTION file in the source package root. That URL can be read with EJAM::url_package("docs"), which currently returns https://public-environmental-data-partners.github.io/EJAM. Prior to mid-2025, documentation web pages had been on GitHub Pages at URLs related to the USEPA/EJAM and USEPA/EJAM-open repositories, but those pages may now be archived, unpublished, or otherwise obsolete.