Render and update the function reference manual, vignettes, README, NEWS, CHANGELOG, LICENSE, and CODE_OF_CONDUCT sections, if they exist. This function overwrites the content of the 'docs/' folder. See details below.
render_docs(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE, ...)Path to the package root directory.
Logical. Print Rmarkdown or Quarto rendering output.
Logical. Render man pages and vignettes in parallel using the future framework. In addition to setting this argument to TRUE, users must define the parallelism plan in future. See the examples section below.
Logical. If TRUE and a man page or vignette has not changed since the last call to render_docs(), that file is skipped. File hashes are stored in altdoc/freeze.rds. If that file is deleted, all man pages and vignettes will be rendered anew.
Additional arguments are ignored.
The settings files in the altdoc/ directory can include $ALTDOC variables which are replaced automatically by altdoc when calling render_docs():
$ALTDOC_PACKAGE_NAME: Name of the package from DESCRIPTION.
$ALTDOC_PACKAGE_VERSION: Version number of the package from DESCRIPTION
$ALTDOC_PACKAGE_URL: First URL listed in the DESCRIPTION file of the package.
$ALTDOC_PACKAGE_URL_GITHUB: First URL that contains "github.com" from the URLs listed in the DESCRIPTION file of the package. If no such URL is found, lines containing this variable are removed from the settings file.
$ALTDOC_MAN_BLOCK: Nested list of links to the individual help pages for each exported function of the package. The format of this block depends on the documentation generator.
$ALTDOC_VIGNETTE_BLOCK: Nested list of links to the vignettes. The format of this block depends on the documentation generator.
$ALTDOC_VERSION: Version number of the altdoc package.
Also note that you can store images and static files in the altdoc/ directory. All the files in this folder are copied to docs/ and made available in the root of the website, so you can link to them easily.
When you call render_docs(), altdoc will automatically paste the content of one of these three files to the top of a document:
altdoc/preamble_vignettes_qmd.yml
altdoc/preamble_vignettes_rmd.yml
altdoc/preamble_man_qmd.yml
The README file uses the vignette preamble.
To preempt this behavior, add your own preamble to the README file or to a vignette.
When working on a package, running render_docs() to preview changes can be a time-consuming road block. The argument freeze = TRUE tries to improve the experience by preventing rerendering of files that have not changed since the last time render_docs() was ran. Note that changes to package internals will not cause a rerender, so rerendering the entire docs can still be necessary.
For non-Quarto formats, this is done by creating a freeze.rds file in altdoc/ that is able to determine which documentation files have changed.
For the Quarto format, we rely on the Quarto freeze feature. Freezing a document needs to be set either at a project or per-file level. Freezing a document needs to be set either at a project or per-file level. To do so, add to either quarto_website.yml or the frontmatter of a file:
execute:
freeze: auto
When the code-link format setting is true in altdoc/quarto_website.yml and the downlit package is installed, altdoc will use the downlit package to replace the function names on the package website by links to web-based package documentation. This works for base R libraries and any package published on CRAN.
To allow internal links to functions documented by altdoc, we need to include links to correct URLs in the altdoc/pkgdown.yml file. By default, this file is populated with links to the first URL in the DESCRIPTION.
Importantly, downlit requires the pkgdown.yml file to be live on the website to create links. This means that links will generally not be updated when making purely local changes. Also, links may not be updated the first time an altdoc website is published to the web.
This function searches the root directory and the inst/ directory for specific filenames, renders/converts/copies them to the docs/ directory. The order of priority for each file is established as follows:
docs/README.md
README.md, README.qmd, README.Rmd
docs/NEWS.md
NEWS.md, NEWS.txt, NEWS, NEWS.Rd
Note: Where possible, Github contributors and issues are linked automatically.
docs/CHANGELOG.md
CHANGELOG.md, CHANGELOG.txt, CHANGELOG
docs/CODE_OF_CONDUCT.md
CODE_OF_CONDUCT.md, CODE_OF_CONDUCT.txt, CODE_OF_CONDUCT
docs/LICENSE.md
LICENSE.md, LICENSE.txt, LICENSE
docs/LICENCE.md
LICENCE.md, LICENCE.txt, LICENCE
if (interactive()) {
render_docs()
# parallel rendering
library(future)
plan(multicore)
render_docs(parallel = TRUE)
}
Run the code above in your browser using DataLab