pkgdown (version 1.0.0)

build_reference: 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, 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().

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 40x40 (for regular display) or 80x80 (if you want retina display). Icons are matched to topics by aliases.

Examples

# NOT RUN {
# 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)
# }
# NOT RUN {
# }
# NOT RUN {
# This code won't generally be run by CRAN. But it
# will be run by pkgdown
b <- 10
a + b
# }