gen_pkgdown_ref: Generate pkgdown reference index

In salim-b/pkgpurl: Facilitate Authoring R Packages in the R Markdown File Format

Generate pkgdown reference index

Description

Generates the pkgdown reference index based on the heading hierarchy structure of a package's main .Rmd file.

Usage

gen_pkgdown_ref(rmd, env = parent.frame())

Arguments

rmd	The (R) Markdown file content as a character scalar.
env	Environment to evaluate R Markdown inline code expressions in.

Details

Basically, all elements of the pkgdown reference index except desc keys are derived from rmd's Markdown headings and their hierarchy. The desc keys, however, are assembled from the paragraph(s) below some specially named headings. See below for details.

Value

A list.

Special headings

Headings that exactly match certain strings (case-insensitive, but without any inline formatting or additional text) are treated specially. Here's an overview:

Headings	Meaning
DESCRIPTION	Paragraph(s) below this heading, which in turn is hierarchically below a title or subtitle heading, are used as the description for this very (sub)title (desc in the pkgdown reference index).
EXPORTED	Will never be used as title or subtitle in the pkgdown reference index (i.e. ignored). Simply serves as a (usually top-level) heading to indicate that the objects defined below it are exported by the package.
INTERNAL , NOTES , TEMPORARY, TMP	Everything that's hierarchically below one of these headings is completely ignored for pkgdown reference index generation.

Parsing rules

To be able to unambiguously map an .Rmd file's heading hierarchy to the pkgdown reference index, some parsing rules are necessary. Attention must be paid to the fact that, while (R) Markdown supports up to six heading levels (corresponding to HTML's ⁠<h1>⁠–⁠<h6>⁠ tags), the pkgdown reference index only supports up to two (title and subtitle).

The following rules define how the reference index is generated:

1. Headings below a heading named INTERNAL, NOTES, TEMPORARY or TMP (case-insensitive, but without any inline formatting) are simply ignored when generating the reference index.

2. Every heading that is a) inline-formatted as verbatim and b) doesn't contain any whitespace characters is considered to be the name of a help topic (usually the name of a function or dataset) to be included in the reference index. This maps to the contents key of the reference index' YAML.

3. Non-help-topic headings above help topic headings are used as reference index (sub)titles as far as hierarchical nesting allows. More precisely, non-help-topic headings of the highest two levels above the help topic heading are used as title and subtitle, the rest of the headings above the help topic heading is ignored – and a heading named EXPORTED (case-insensitive, but without any inline formatting) is always ignored regardless of its level. This maps to the title and subtitle keys of the reference index' YAML.

4. Paragraph(s) below a heading named DESCRIPTION (case-insensitive, but without any inline formatting), that in turn is hierarchically below a title or subtitle heading, are used as the description for the respective (sub)title. This maps to the desc key of the reference index' YAML.

Parsing example

An example might better explain how the parsing rules work than a thousand words, so here's a simplified one.

When fed to gen_pkgdown_ref(), the following R Markdown content...

---
editor_options:
  markdown:
    wrap: 80
---

# `main_fn`

The fn below is under no title or subtitle in the pkgdown index.

```{r}
main_fn <- function(...) {...}
```

# First group of fns

## DESCRIPTION

The description text for *First group of fns*.

## `group_wide_fn`

The fn below is only under a title, but no subtitle in the pkgdown index.

```{r}
group_wide_fn <- function(...) {...}
```

## Some subgroup

The fns below are both under a title and subtitle in the pkgdown index.

### `subgroup_fn_1`

```{r}
subgroup_fn_1 <- function(...) {...}
```

### `subgroup_fn_2`

```{r}
subgroup_fn_2 <- function(...) {...}
```

### Sub-subgroup

The above *Sub-subgroup* heading is ignored for the pkgdown index because the
latter only supports up to two heading levels.

The fn below thus moves one hierarchy level up in the pkgdown index.

#### `sub_subgroup_fn`

```{r}
sub_subgroup_fn <- function(...) {...}
```

## Another subgroup

### DESCRIPTION

The description text for *Another subgroup*.

### `another_subgroup_fn`

```{r}
another_subgroup_fn <- function(...) {...}
```

# Second group of fns

## Yet another subgroup

### `yet_another_subgroup_fn`

```{r}
yet_another_subgroup_fn <- function(...) {...}
```

...yields this pkgdown index (converted to YAML):

reference:
- contents: main_fn
- title: First group of fns
  desc: The description text for *First group of fns*.
- contents: group_wide_fn
- subtitle: Some subgroup
- contents:
  - subgroup_fn_1
  - subgroup_fn_2
  - sub_subgroup_fn
- subtitle: Another subgroup
  desc: The description text for *Another subgroup*.
- contents: another_subgroup_fn
- title: Second group of fns
- subtitle: Yet another subgroup
- contents: yet_another_subgroup_fn

Inline R code

R Markdown inline code is fully supported in headings and descriptions, except for the above mentioned special headings (otherwise, they're not recognized as special headings anymore).

Examples

if (pal::is_pkg_installed("tinkr")) {
  yay::gh_text_file(path = "Rmd/pal.Rmd",
                    owner = "salim-b",
                    name = "pal") |>
    pkgpurl::gen_pkgdown_ref() |>
    yaml::as.yaml() |>
    cat()
}

salim-b/pkgpurl documentation built on June 2, 2025, 8:26 a.m.