build_reference: Build reference section

Description Usage Arguments YAML config Icons Examples

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

1
2
3
4
5
build_reference(pkg = ".", lazy = TRUE, examples = TRUE,
  run_dont_run = FALSE, mathjax = TRUE, seed = 1014,
  path = "docs/reference", depth = 1L)

build_reference_index(pkg = ".", path = "docs/reference", depth = 1L)

Arguments

pkg

Path to source package. If R working directory is not set to the source directory, then pkg must be a fully qualified path to the source directory (not a relative path).

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.

path

Output path. Relative paths are taken relative to the pkg directory.

depth

Depth of path relative to root of documentation. Used to adjust relative links in the navbar.

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:

1
2
3
4
5
6
7
8
9
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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 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

aaronrudkin/pkgdown documentation built on May 23, 2019, 4:23 p.m.