Skip to contents

Updating Documentation

Source: vignettes/dev_update_documentation.Rmd
dev_update_documentation.Rmd

This document addresses how to update the documentation supporting the package.

Updating package documentation

The R package is documented in webpages (and in standard help documents viewable in RStudio). Documentation will generally need to be updated in preparation for a new release of the package. Updates may be needed in the following:

  1. Package: overall, package-wide information/ 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/ documents

  • Package-wide documentation files can be updated/edited and include the following: DESCRIPTION, README.Rmd (for README, edit the README.RmdNOT the 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, and others.

  • Some of these are used by and shown by the github.com 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 package version number and URLs of the package repository, etc.

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

  • you might find it useful to check docs with tools::checkDocFiles(“EJAM”)

Datasets: reference docs explaining the datasets

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

  • most dataset documentation is created/updated alongside the code that created or updates those datasets. That is best done starting with the overarching file called data-raw/datacreate_0_UPDATE_ALL_DATASETS.R which helps walk through updating various datasets as needed and their documentation is often updated in that same process.

  • 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/edited as .Rmd files in the vignettes folder. You can test one using something like pkgdown::build_article() before trying to rebuild the whole pkgdown site.

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

User Guide: help for people using the web app

  • If you change the UI then new screenshots are needed for a new version of the User Guide that was stored as a .pdf document.

Spell-checking package-wide

  • To run a spell check (see 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 you can use ctrl-shift-F to search in all files for a flagged term to check if it is actually a problem

  • If you wanted to update the WORDLIST (list of words to ignore spelling of)

    # 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:::functions_in_pkg( '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 should be updated right after any of the above are edited/created. These pkgdown-based webpages should be updated by someone who is managing the package, as follows:

  • The first step in updating those web pages is updating the yml 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 webpages of documentation, such as the names of any vignettes files to be shown in the list of articles, which functions are included in the reference pages index, etc. Any new or removed or renamed functions/ vignettes/ datasets, or changes in what is exported, will require edits to the .yml file.

  • The pkgdown-based webpages should be updated by someone who is managing the package, and they should use the update_pkgdown() function found in data-raw/datacreate_0_UPDATE_ALL_DOCUMENTATION_pkgdown.R You have to source() that file and then use the function that it defines. Via that function, the pages get rebuilt by the pkgdown R package, based on the above files and all other documentation from .R and .md files. For more information about using the pkgdown package to create documentation in the form of webpages, see pkgdown articles. The documentation is created/updated using the roxygen2 and pkgdown R packages, which read information from the .R files in the R folder, from .Rmd file vignettes (aka “articles”) in the vignettes folder, and from the _pkgdown.yml file in the root folder of the source package. The roxygen2 package reads the .R files to create the .Rd files in the man/ directory. The pkgdown package uses all those files as well as DESCRIPTION and others, to generate a website for the package, first created as files in the docs/ folder, which are then published via github actions and the github repository settings, to be hosted on GitHub Pages. The packages devtools and usethis are also relevant.

  • the package’s github repository settings define which branch and which folder should hold the html files for deployment (see github and pkgdown documentation on that)

  • the package’s Github Actions can be used to deploy the webpages when triggered by an event like any push to the main branch, for example.

  • depending on which folder you publish/deploy from, you might have to remove that folder from .gitignore in case it was listed there via some pkgdown or usethis function.