In maurolepore/pkgdoc: Reference Documented R Objects Across Multiple Packages

knitr::opts_chunk$set(
  echo = TRUE,
  message = FALSE,
  warning = FALSE,
  collapse = TRUE,
  comment = "#>"
)

This reference overwrites the default Reference of pkgdown. It is a vignette stored in vignettes/siteonly. The _pkgdown.yml file contains this header:

navbar:
  type: default
  left:
  - text: "Reference"
    href: articles/siteonly/reference.html

You can see pkgdoc in action here.

Let's build references with pkgdoc, manipulate data with dplyr, and build tables with knitr and DT.

library(pkgdoc)
library(dplyr)
library(knitr)
library(DT)

All functions in pkgdoc

Let's see what documentation we have to decide the best way to present it.

docs <- reference_package("pkgdoc", url = "https://maurolepore.github.io/")
docs

The functions are few and we can show them all at once. But let's tweak the output:

Let's emphasize the main functions by pushing the helper function to the bottom.
Let's hide the concept column.
Let's build transform the ugly text in topic and package into links.

(The column package isn't helpful but I'll leave it to show the link.)

docs %>% 
  arrange(desc(concept)) %>% 
  select(-concept) %>% 
  knitr::kable()

Okay, but pkgdown does that already. To see the value of pkgdoc let's explore a more complex example.

Example: Referencing documentation across multiple packages

To show how to reference documentation across multiple packages we will use the fgeo meta-package fgeo.

library(fgeo)

fgeo:::fgeo_packages()

fgeo_url <- "https://forestgeo.github.io/"

Searching

You can reference a large number of documentation. Instead of scanning a long list your readers may prefer to search.

# Pulling documentation of all fgeo packages
docs <- fgeo:::fgeo_packages() %>% 
  purrr::map_dfr(reference_package, url = fgeo_url) %>% 
  select(-package, -concept) %>% 
  unique()

docs %>% 
  DT::datatable(
    escape = FALSE,
    rownames = NULL,
    options = list(
      # f: filter, t: table, i: information
      dom = "fti",
      search = list(search = "topography")
    )
  )

Scanning

If the list isn't too long, your reader may scan the entire list. Sometimes it is nice to know you have seen it all.

Grouping multiple packages

You may cherry-pick all documentation from specific packages.

reference_package(
  c("fgeo.x", "fgeo.analyze"), 
  url = fgeo_url
 ) %>% 
  arrange(concept) %>% 
  select(-package, -concept) %>% 
  knitr::kable()

Grouping concepts from multiple packages

You may cherry-pick all documentation matching some concept. Create topics by adding the tag @family in your documentation (see roxygen2).

reference_concept(
  c("habitat functions", "plot functions"),
  url = fgeo_url,
  # limit the search of documentation within these packages
  packages = fgeo:::fgeo_packages(),
  ) %>% 
  arrange(concept) %>%
  select(-package, -concept) %>% 
  knitr::kable()