Reference

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
#> # A tibble: 3 x 5
#>   topic               alias       title               concept   package         
#>   <glue>              <chr>       <chr>               <chr>     <glue>          
#> 1 <a href=https://ma… reference_… Pick documentation… retrieve… <a href=https:/…
#> 2 <a href=https://ma… s3_strip_c… Strip the class pa… helper    <a href=https:/…
#> 3 <a href=https://ma… search_docs Dataframe the docu… retrieve… <a href=https:/…

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()

topic	alias	title	package
?	reference_package, reference_concept	Pick documentation matching some concepts or package names.	pkgdoc
?	search_docs	Dataframe the documentation of installed packages.	pkgdoc
?	s3_strip_class	Strip the class part of attached S3 methods (do nothing with other functions).	pkgdoc

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()
#> [1] "fgeo.analyze" "fgeo.plot"    "fgeo.tool"    "fgeo.x"       "fgeo"

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()

topic	alias	title
?	datasets, elevation, habitat, stem5, stem6, tree5, tree6, vft_4quad, tree6_3species	Access data via ‘library(fgeo.x)’ or ‘fgeo.x::’.
?	download_data	Access data stored online.
?	example_path	Access data stored in system files.
?	recruitment_ctfs, mortality_ctfs, growth_ctfs	Recruitment, mortality, and growth.
?	abundance_byyr, basal_area_byyr	Create tables of abundance and basal area by year.
?	abundance, basal_area	Abundance and basal area, optionally by groups.
?	recruitment_ctfs, mortality_ctfs, growth_ctfs	Recruitment, mortality, and growth.
?	recruitment_ctfs, mortality_ctfs, growth_ctfs	Recruitment, mortality, and growth.
?	fgeo_habitat	Create habitat data from measures of topography.
?	fgeo_topography	Create topography data: convexity, slope, and mean elevation.
?	fgeo_habitat	Create habitat data from measures of topography.
?	fgeo_topography	Create topography data: convexity, slope, and mean elevation.
?	tt_test	Torus Translation Test to determine habitat associations of tree species.
?	summary	Summary of ‘tt_test()’ results.

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()