R: Build reference section

build_reference {pkgdown}

R Documentation

Build reference section

Description

By default, pkgdown will generate an index that simply lists all the functions in alphabetical order. To override this, provide a reference section in your _pkgdown.yml as described below.

Usage

build_reference(pkg = ".", lazy = TRUE, document = FALSE,
  examples = TRUE, run_dont_run = FALSE, mathjax = TRUE, seed = 1014,
  override = list(), preview = NA)

build_reference_index(pkg = ".")

Arguments

`pkg`	Path to package.
`lazy`	If `TRUE`, only rebuild pages where the `.Rd` is more recent than the `.html`. This makes it much easier to rapidly protoype. It is set to `FALSE` by `build_site()`.
`document`	If `TRUE`, will run `devtools::document()` before updating the site.
`examples`	Run examples?
`run_dont_run`	Run examples that are surrounded in \dontrun?
`mathjax`	Use mathjax to render math symbols?
`seed`	Seed used to initialize so that random examples are reproducible.
`override`	An optional named list used to temporarily override values in `_pkgdown.yml`
`preview`	If `TRUE`, or `is.na(preview) && interactive()`, will preview freshly generated section in browser.

YAML config

To tweak the index page, you need a section called reference which provides a list of sections containing, a title, list of contents, and optional description.

For example, the following code breaks up the functions in pkgdown into two groups:

reference:
- title: Render components
  desc:  Build each component of the site.
  contents:
  - starts_with("build_")
  - init_site
- title: Templates
  contents:
  - render_page

Note that contents can contain either a list of function names, or if the functions in a section share a common prefix or suffix, you can use starts_with("prefix") and ends_with("suffix") to select them all. For more complex naming schemes you can use an aribrary regular expression with matches("regexp"). You can also use a leading - to exclude matches from a section. By default, these functions that match multiple topics will exclude topics with keyword "internal". To include, use (e.g.) starts_with("build_", internal = TRUE).

Alternatively, you can selected topics that contain specified concepts with has_concept("blah"). Concepts are not currently well-supported by roxygen2, but may be useful if you write Rd files by hand.

pkgdown will check that all non-internal topics are included on this page, and will generate a warning if you have missed any.

Figures

You can control the default rendering of figues by specifying the figures field in _pkgdown.yml. The default settings are equivalent to:

figures:
  dev: grDevices::png
  dpi: 96
  dev.args: []
  fig.ext: png
  fig.width: 7.2916667
  fig.height: ~
  fig.retina: 2
  fig.asp: 1.618

Icons

You can optionally supply an icon for each help topic. To do so, you'll need a top-level icons directory. This should contain .png files that are either 30x30 (for regular display) or 60x60 (if you want retina display). Icons are matched to topics by aliases.

Examples

# This example illustrates some important output types
# The following output should be wrapped over multiple lines
a <- 1:100
a

cat("This some text!\n")
message("This is a message!")
warning("This is a warning!")

# This is a multi-line block
{
  1 + 2
  2 + 2
}

## Not run: 
stop("This is an error!", call. = FALSE)

## End(Not run)


# This code won't generally be run by CRAN. But it
# will be run by pkgdown
b <- 10
a + b

[Package pkgdown version 1.1.0 Index]