Get started • dverse

This article shows how to create a global search for any collection of R packages, i.e. a universe. Your universe may be on CRAN, large, and popular like the tidyverse. But it may also be not on CRAN, small, company-specific or personal.

The example here uses the ‘toyverse’ – a toy universe containing the packages glue and dplyr.

You need:

the package dverse to document your universe,
each package in the ‘toyverse’ to access the documentation metadata,
DT to create a searchable table.

library(dverse)

# toyverse
library(glue)
library(dplyr)

library(DT)

dverse::document_universe() takes the names of the packages in the ‘toyverse’, and a template pointing to each help file (topic) in each package.

toyverse <- c("glue", "dplyr")
# For example: https://dplyr.tidyverse.org/reference/select.html
template <- "https://{package}.tidyverse.org/reference/{topic}.html"

docs <- dverse::document_universe(toyverse, template)
docs
#> # A tibble: 138 × 7
#>    topic                               alias title concept type  keyword package
#>    <chr>                               <chr> <chr> <chr>   <chr> <chr>   <chr>  
#>  1 <a href=https://dplyr.tidyverse.or… acro… Appl… NA      help  NA      dplyr  
#>  2 <a href=https://dplyr.tidyverse.or… add_… Conv… NA      help  intern… dplyr  
#>  3 <a href=https://dplyr.tidyverse.or… all_… Flex… NA      help  intern… dplyr  
#>  4 <a href=https://dplyr.tidyverse.or… all_… Appl… NA      help  NA      dplyr  
#>  5 <a href=https://dplyr.tidyverse.or… args… Help… NA      help  intern… dplyr  
#>  6 <a href=https://dplyr.tidyverse.or… arra… Orde… single… help  NA      dplyr  
#>  7 <a href=https://dplyr.tidyverse.or… arra… Arra… NA      help  intern… dplyr  
#>  8 <a href=https://glue.tidyverse.org… as_g… Coer… NA      help  NA      glue   
#>  9 <a href=https://dplyr.tidyverse.or… auto… Copy… NA      help  NA      dplyr  
#> 10 <a href=https://dplyr.tidyverse.or… back… Data… NA      help  intern… dplyr  
#> # ℹ 128 more rows

You may need to exclude some topics, such as reexported objects from other packages. Because topics outside your universe yield broken links, you can exclude them with dverse::is_online().

docs %>% filter(!dverse::is_online(topic))
#> # A tibble: 1 × 7
#>   topic                                alias title concept type  keyword package
#>   <chr>                                <chr> <chr> <chr>   <chr> <chr>   <chr>  
#> 1 <a href=https://dplyr.tidyverse.org… dist… Same… NA      help  intern… dplyr

online <- docs %>% filter(dverse::is_online(topic))

Consider the different kinds of documentation in your universe.

online %>% count(type, keyword)
#> # A tibble: 4 × 3
#>   type     keyword      n
#>   <chr>    <chr>    <int>
#> 1 help     datasets     3
#> 2 help     internal    52
#> 3 help     NA          69
#> 4 vignette NA          13

You may organize the documentation however you like. For inspiration see the pactaverse, the toy ‘admiralverse’, fgeo and tidymodels.

Here it makes sense to place vignettes, datasets, and public functions in separate tables.

Vignettes

Here are all the vignettes available across packages in the ‘toyverse’. Click on each topic to read its corresponding vignette.

vignettes <- online %>% filter(type == "vignette")

vignettes %>%
  distinct(topic, title, package) %>%
  datatable(escape = FALSE)

You don’t see what you expect?

This works with vignettes but not articles, so usethis::use_vignette() not usethis::use_article().
When you install the packages in your universe ensure to install the vignettes. Vignettes install by default when you install your packages from CRAN with install.packages() or pak::pak(). But if you install them from source with devtools::install() or remotes::install_github(), then you need build_vignettes = TRUE.

Datasets

Here are all the datasets. Click on each topic to read about it.

datasets <- online %>% filter(keyword == "datasets")

datasets %>%
  distinct(topic, title, package) %>%
  datatable(escape = FALSE)

Functions

Here are all the functions, except internal ones. Click on each topic to read about it.

internal <- online %>% filter(keyword == "internal")

public <- online %>%
  anti_join(vignettes) %>%
  anti_join(datasets) %>%
  anti_join(internal)

public %>%
  distinct(topic, title, package) %>%
  datatable(escape = FALSE)

Learn More

To learn more see the toy ‘admiralverse’ meta-package – which models the main use case of dverse.