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,
examples = TRUE,
run_dont_run = FALSE,
seed = 1014,
override = list(),
preview = NA,
devel = TRUE,
document = "DEPRECATED",
topics = NULL
)
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 toFALSE
bybuild_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
, oris.na(preview) && interactive()
, will preview freshly generated section in browser.- devel
Determines how code is loaded in order to run examples. If
TRUE
(the default), assumes you are in a live development environment, and loads source package withpkgload::load_all()
. IfFALSE
, uses the installed version of the package.- document
Deprecated Use
devel
instead.- topics
Build only specified topics. If supplied, sets
lazy
andpreview
toFALSE
.
Reference index
To tweak the index page, add a section called reference
to _pkgdown.yml
.
It can contain three different types of element:
A title (
title
+desc
), which generates an row containing an<h2>
with optional paragraph description.A subtitle (
subtitle
+desc
), which generates an row containing an<h3>
with optional paragraph description.A list of topics (
contents
), which generates one row for each topic, with a list of aliases for the topic on the left, and the topic title on the right.
(For historical reasons you can include contents
with a title or
subtitle, but this is no longer recommended).
Most packages will only need to use title
and contents
components.
For example, here's a snippet from the YAML that pkgdown uses to generate
its own reference index:
reference:
- title: Build
desc: Build a complete site or its individual section components.
- contents:
- starts_with("build_")
- title: Templates
- contents:
- template_navbar
- render_page
Bigger packages, e.g. ggplot2, may need an additional layer of structure in order to clearly organise large number of functions:
reference:
- title: Layers
- subtitle: Geoms
desc: Geom is short for geometric element
- contents:
- starts_with("geom")
- subtitle: Stats
desc: Statistical transformations transform data before display.
contents:
- starts_with("stat")
desc
can use markdown, and if you have a long description it's a good
idea to take advantage of the YAML >
notation:
desc: >
This is a very _long_ and **overly** flowery description of a
single simple function. By using `>`, it's easy to write a description that runs over multiple lines.
Topic matching
contents
can contain:
Individual function/topic names.
Weirdly named functions with doubled quoting, once for YAML and once for R, e.g.
"`+.gg`"
.starts_with("prefix")
to select all functions with common prefix.ends_with("suffix")
to select all functions with common suffix.matches("regexp")
for more complex regular expressions.has_keyword("x")
to select all topics with keyword "x";has_keyword("datasets")
selects all data documentation.has_concept("blah")
to select all topics with concept "blah". If you are using roxygen2,has_concept()
also matches family tags, because roxygen2 converts them to concept tags.lacks_concepts(c("concept1", "concept2"))
to select all topics without those concepts. This is useful to capture topics not otherwise captured byhas_concepts()
.Topics from other installed packages, e.g.
rlang::is_installed()
(function name) orsass::font_face
(topic name).
All functions (except for has_keywords()
) automatically exclude internal
topics (i.e. those with \keyword{internal}
). You can choose to include
with (e.g.) starts_with("build_", internal = TRUE)
.
Use a leading -
to remove topics from a section, e.g. -topic_name
,
-starts_with("foo")
.
pkgdown will check that all non-internal topics are included on the reference index page, and error if you have missed any.
Missing topics
pkgdown will warn if there are (non-internal) topics that not listed in the reference index. You can suppress these warnings by listing the topics in section with "title: internal" (case sensitive) which will not be displayed on the reference index.
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: ragg::agg_png
dpi: 96
dev.args: []
fig.ext: png
fig.width: 7.2916667
fig.height: ~
fig.retina: 2
fig.asp: 1.618
bg: NA
other.parameters: []
Most of these parameters are interpreted similarly to knitr chunk
options. other.parameters
is a list of parameters
that will be available to custom graphics output devices such
as HTML widgets.