build_reference: Build reference section

In Paradigm4/pkgdown: Make Static HTML Documentation for a Package

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,
  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 to FALSE by build_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.
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 with pkgload::load_all(). If FALSE, uses the installed version of the package.
document	Deprecated Use devel instead.
topics	Build only specified topics. If supplied, sets lazy`` and previewtoFALSE'.

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 by has_concepts().

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 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 30x30 (for regular display) or 60x60 (if you want retina display). Icons are matched to topics by aliases.

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

Paradigm4/pkgdown documentation built on June 3, 2020, 12:30 a.m.