render_docs {altdoc} | R Documentation |
Update documentation
Description
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.
Usage
render_docs(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE)
Arguments
path |
Path to the package root directory. |
verbose |
Logical. Print Rmarkdown or Quarto rendering output. |
parallel |
Logical. Render man pages and vignettes in parallel using the |
freeze |
Logical. If TRUE and a man page or vignette has not changed since the last call to |
Details
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
Altdoc variables
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 fromDESCRIPTION
. -
$ALTDOC_PACKAGE_VERSION
: Version number of the package fromDESCRIPTION
-
$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.
Altdoc preambles
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.
Examples
if (interactive()) {
render_docs()
# parallel rendering
library(future)
plan(multicore)
render_docs(parallel = TRUE)
}