build_reference: Build reference section

Description

By default, pkgdown will generate an index that lists all 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, 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 prototype. 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?

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, add a section called reference to _pkgdown.yml which provides a list of sections containing, a title, list of contents, and an 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 arbitrary 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 the Rd keyword "internal". To include these, use starts_with("build_", internal = TRUE).

You can alo select topics that contain specified Rd concepts with has_concept("blah").

You can provide long descriptions for groups of functions using the YAML > notation:

desc: >
  This is a very long and overly flowery description of a
  single simple function.

If you have functions with odd names (e.g. that start with a plus symbol +), you can include them by double-escaping. This YAML entry adds the +.gg function to the ggplot2 documentation:

- "`+.gg`"

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 figures 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.