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())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.
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:
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.
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
contentskey of the reference index' YAML.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
titleandsubtitlekeys of the reference index' YAML.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
desckey 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_fnInline 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()
}
#> reference:
#> - title: Statistical computing / numbers
#> - contents:
#> - safe_seq_len
#> - safe_max
#> - safe_min
#> - round_to
#> - stat_mode
#> - title: Data frames / Tibbles
#> - contents:
#> - assert_cols
#> - is_equal_df
#> - reduce_df_list
#> - title: Lists
#> - contents: as_flat_list
#> - title: Strings
#> - subtitle: Vectorized
#> - contents:
#> - as_chr
#> - escape_lf
#> - prettify_nr
#> - sentenceify
#> - capitalize_first
#> - wrap_chr
#> - subtitle: Non-vectorized
#> - contents:
#> - as_line_feed_chr
#> - dsv_colnames
#> - subtitle: Collapsed into character scalar
#> - contents:
#> - as_str
#> - as_comment_str
#> - enum_str
#> - fuse_regex
#> - prose_ls
#> - title: Filesystem paths
#> desc: Functions to work with filesystem paths.
#> - contents:
#> - path_mod_time
#> - flatten_path_tree
#> - draw_path_tree
#> - title: Dots
#> desc: |-
#> Extending [rlang's *check dots* functions](https://rlang.r-lib.org/reference/index.html#check-dots), making the use of [R's `...` argument
#> placeholder](https://rdrr.io/r/base/dots.html) yet another bit safer.
#> - contents: check_dots_named
#> - title: R packages
#> - contents:
#> - ls_pkg
#> - use_pkg
#> - assert_pkg
#> - is_pkg_installed
#> - is_pkg_cran
#> - is_pkg_dir
#> - is_pkgdown_dir
#> - exists_in_namespace
#> - reason_pkg_required
#> - subtitle: Package configuration
#> desc: Functions around pal's canonicalized way to package configuration.
#> - contents:
#> - pkg_config_val
#> - pkg_config_val_default
#> - has_pkg_config_val
#> - augment_pkg_config
#> - print_pkg_config
#> - subtitle: Package DESCRIPTION
#> desc: Extending the [**desc**](https://github.com/r-lib/desc#readme) package.
#> - contents:
#> - desc_list
#> - desc_value
#> - desc_dep_vrsn
#> - desc_url_git
#> - subtitle: Package documentation
#> desc: Complementing and extending the [**roxygen2**](https://roxygen2.r-lib.org/)
#> package.
#> - contents:
#> - fn_param_defaults
#> - enum_fn_param_defaults
#> - roxy_to_md_links
#> - roxy_blocks
#> - roxy_obj
#> - roxy_tag_value
#> - title: (Pandoc) Markdown
#> - contents:
#> - md_verb
#> - as_md_list
#> - as_md_vals
#> - as_md_val_list
#> - pipe_table
#> - strip_md
#> - strip_md_footnotes
#> - subtitle: CommonMark parsing
#> desc: Extending the [**commonmark**](https://github.com/r-lib/commonmark#readme)
#> package.
#> - contents:
#> - md_to_xml
#> - md_xml_subnode_ix
#> - xml_to_md
#> - title: R Markdown / knitr
#> - contents:
#> - build_readme
#> - knitr_table_format
#> - strip_yaml_header
#> - subtitle: Output formats
#> desc: |-
#> [Custom R Markdown output formats](https://bookdown.org/yihui/rmarkdown/new-formats.html) which can be used in addition to the [default output
#> formats](https://bookdown.org/yihui/rmarkdown/output-formats.html).
#> - contents: gitlab_document
#> - title: HTML widgets
#> desc: Extending the [**htmlwidgets**](https://www.htmlwidgets.org/) package.
#> - contents:
#> - write_widget
#> - write_widget_deps
#> - title: checkmate
#> desc: Extending the [**checkmate**](https://mllg.github.io/checkmate/) package.
#> - contents:
#> - assert_class_any
#> - assert_df_or_tibble
#> - assert_inf_count
#> - title: cli
#> desc: Extending the [**cli**](https://cli.r-lib.org/) package.
#> - contents:
#> - cli_qty_lgl
#> - cli_no_lgl
#> - cli_progress_step_quick
#> - cli_process_expr
#> - title: Git
#> desc: Extending the [**gert**](https://docs.ropensci.org/gert/) and [**git2r**](https://docs.ropensci.org/git2r/)
#> packages.
#> - contents:
#> - git_file_mod_time
#> - git_remote_tree_url
#> - title: HTTP
#> desc: |-
#> Extending the [**httr**](https://httr.r-lib.org/) and [**httr2**](https://httr2.r-lib.org/) packages that wrap the [curl](https://jeroen.cran.dev/curl/)
#> package.
#> - contents:
#> - assert_mime_type
#> - is_http_success
#> - is_url
#> - req_cached
#> - title: TOML
#> - contents:
#> - toml_read
#> - toml_validate
#> - title: System interaction
#> - contents:
#> - test_cli
#> - assert_cli
#> - path_script
#> - title: Miscellaneous
#> - contents:
#> - capture_print
#> - cat_lines
#> - cols_regex
#> - mime_to_ext
#> - rename_from
#> - arrange_by
#> - when