url_template can now take explicit vignettes (#39)

* url_template can now take explicit vignettes

* Polish README

* Spelling

Author: maurolepore

R/document_universe.R

@@ -5,16 +5,30 @@ document_universe_impl <- function(x, url_template = NULL) {
   out <- tidy_reference(pick, strip_s3class = TRUE)
 
   if (!is.null(url_template)) {
+    manual <- url_template[[1]]
+
+    if (identical(length(url_template), 1L)) {
+      vignettes <- url_template[[1]]
+    }
+    if (identical(length(url_template), 2L)) {
+      vignettes <- url_template[[2]]
+    }
+    if (length(url_template) > 2L) {
+      longer <- length(url_template)
+      cli::cli_abort("`url_template` must be of length 1 or 2, not {longer}.")
+    }
+
+
     out <- mutate(
       out,
       topic = dplyr::case_when(
         .data$type == "help" ~ to_href(
           .data$topic,
-          template = glue::glue(url_template)
+          template = glue::glue(manual)
         ),
         .data$type == "vignette" ~ to_href(
           .data$topic,
-          template = glue::glue(vignettes_template(url_template))
+          template = glue::glue(vignettes_template(vignettes))
         ),
         .default = .data$topic
       )
@@ -40,10 +54,18 @@ vignettes_template <- function(template) {
 #' meta-package.
 #'
 #' @param x A character vector giving concepts or package names to match.
-#' @param url_template Character. A template to generate links to documentation
-#'   based on the column names of the output -- typically `package` and `topic`,
-#'   e.g. `"https://maurolepore.github.io/{package}/reference/{topic}.html"`
-#'   (`glue::glue()` syntax).
+#' @param url_template Character. A template to generate links to documentation,
+#'   using the syntax of `glue::glue()` to indicate where to insert the values
+#'   from the columns `package` and `topic`.
+#'   * If the vector has length 1, we assume it's for the manual (i.e. what you
+#'   can access with `?`), e.g.:
+#'   `"https://maurolepore.github.io/{package}/reference/{topic}.html"`. The
+#'   template for vignettes will be automatically constructed by replacing
+#'   /reference/ with /articles/, e.g.
+#'   `"https://maurolepore.github.io/{package}/articles/{topic}.html"`. If this
+#'   is invalid, then you'll need to provide a vector of length 2.
+#'   * If the vector has length 2, we assume the first element is for the
+#'   manual and the second element is for vignettes.
 #'
 #' @return A data frame.
 #'
@@ -52,10 +74,13 @@ vignettes_template <- function(template) {
 #' library(glue)
 #' library(tibble)
 #'
-#' url_template <- "https://{package}.tidyverse.org/reference/{topic}.html"
-#' document_universe(c("glue", "tibble"), url_template)
+#' manual <- "https://{package}.tidyverse.org/reference/{topic}.html"
+#' vignettes <- "https://{package}.tidyverse.org/articles/{topic}.html"
+#' document_universe(c("glue", "tibble"), url_template = c(manual, vignettes))
+#'
+#' # Assuming vignettes can be found at */articles/* rather than */reference/*
+#' document_universe(c("glue", "tibble"), url_template = manual)
 document_universe <- function(x, url_template = NULL) {
-  # TODO Refactor to simplify. Comes from the more complex maurolepore/pkgdoc
   out <- document_universe_impl(x = x, url_template = url_template)
   tibble::as_tibble(out)
 }

README.Rmd

@@ -79,17 +79,27 @@ library(glue)
 library(tibble)
 
 demoverse <- c("glue", "tibble")
-# For example: "https://tibble.tidyverse.org/reference/enframe.html"
-template <- "https://{package}.tidyverse.org/reference/{topic}.html"
-docs <- dverse::document_universe(demoverse, template)
-
+# Example: "https://tibble.tidyverse.org/reference/as_tibble.html"
+manual <- "https://{package}.tidyverse.org/reference/{topic}.html"
+docs <- document_universe(demoverse, url_template = manual)
 docs
 ```
 
 `knitr::kable()` turns the URLs into clickable links.
 
 ```{r}
-knitr::kable(head(docs, 3))
+knitr::kable(tail(docs))
+```
+
+`url_template` can take different templates for the manual and vignettes.
+
+```{r}
+manual <- "https://tidyverse.r-universe.dev/{package}/doc/manual.html#{topic}"
+vignettes <- "https://tidyverse.r-universe.dev/articles/{package}/{topic}.html"
+docs_runiverse <- document_universe(demoverse, url_template = c(manual, vignettes))
+docs_runiverse
+
+knitr::kable(tail(docs_runiverse))
 ```
 
 `DT::datatabe()` also provides a search box. See [Get started](https://maurolepore.github.io/dverse/articles/dverse.html).

README.md

@@ -75,10 +75,9 @@ library(glue)
 library(tibble)
 
 demoverse <- c("glue", "tibble")
-# For example: "https://tibble.tidyverse.org/reference/enframe.html"
-template <- "https://{package}.tidyverse.org/reference/{topic}.html"
-docs <- dverse::document_universe(demoverse, template)
-
+# Example: "https://tibble.tidyverse.org/reference/as_tibble.html"
+manual <- "https://{package}.tidyverse.org/reference/{topic}.html"
+docs <- document_universe(demoverse, url_template = manual)
 docs
 #> # A tibble: 46 × 7
 #>    topic                               alias title concept type  keyword package
@@ -99,14 +98,52 @@ docs
 `knitr::kable()` turns the URLs into clickable links.
 
 ``` r
-knitr::kable(head(docs, 3))
+knitr::kable(tail(docs))
+```
+
+| topic | alias | title | concept | type | keyword | package |
+|:---|:---|:---|:---|:---|:---|:---|
+| <a href=https://tibble.tidyverse.org/reference/tribble.html>tribble</a> | tribble | Row-wise tibble creation | NA | help | NA | tibble |
+| <a href=https://glue.tidyverse.org/reference/trim.html>trim</a> | trim | Trim a character vector | NA | help | NA | glue |
+| <a href=https://tibble.tidyverse.org/reference/trunc_mat.html>trunc_mat</a> | trunc_mat | Legacy printing | NA | help | internal | tibble |
+| <a href=https://tibble.tidyverse.org/articles/types.html>types</a> | types | Column types | NA | vignette | NA | tibble |
+| <a href=https://tibble.tidyverse.org/reference/view.html>view</a> | view | View an object | NA | help | NA | tibble |
+| <a href=https://glue.tidyverse.org/articles/wrappers.html>wrappers</a> | wrappers | How to write a function that wraps glue | NA | vignette | NA | glue |
+
+`url_template` can take different templates for the manual and
+vignettes.
+
+``` r
+manual <- "https://tidyverse.r-universe.dev/{package}/doc/manual.html#{topic}"
+vignettes <- "https://tidyverse.r-universe.dev/articles/{package}/{topic}.html"
+docs_runiverse <- document_universe(demoverse, url_template = c(manual, vignettes))
+docs_runiverse
+#> # A tibble: 46 × 7
+#>    topic                               alias title concept type  keyword package
+#>    <chr>                               <chr> <chr> <chr>   <chr> <chr>   <chr>  
+#>  1 <a href=https://tidyverse.r-univer… add_… Add … additi… help  <NA>    tibble 
+#>  2 <a href=https://tidyverse.r-univer… add_… Add … additi… help  <NA>    tibble 
+#>  3 <a href=https://tidyverse.r-univer… as_g… Coer… <NA>    help  <NA>    glue   
+#>  4 <a href=https://tidyverse.r-univer… as_t… Coer… <NA>    help  <NA>    tibble 
+#>  5 <a href=https://tidyverse.r-univer… char… Form… vector… help  <NA>    tibble 
+#>  6 <a href=https://tidyverse.r-univer… depr… Depr… <NA>    help  intern… tibble 
+#>  7 <a href=https://tidyverse.r-univer… digi… Comp… <NA>    vign… <NA>    tibble 
+#>  8 <a href=https://tidyverse.r-univer… enfr… Conv… <NA>    help  <NA>    tibble 
+#>  9 <a href=https://tidyverse.r-univer… engi… Cust… <NA>    vign… <NA>    glue   
+#> 10 <a href=https://tidyverse.r-univer… exte… Exte… <NA>    vign… <NA>    tibble 
+#> # ℹ 36 more rows
+
+knitr::kable(tail(docs_runiverse))
 ```
 
-| topic                                                                          | alias               | title                       | concept  | type | keyword | package |
-| :----------------------------------------------------------------------------- | :------------------ | :-------------------------- | :------- | :--- | :------ | :------ |
-| <a href=https://tibble.tidyverse.org/reference/add_column.html>add\_column</a> | add\_column         | Add columns to a data frame | addition | help | NA      | tibble  |
-| <a href=https://tibble.tidyverse.org/reference/add_row.html>add\_row</a>       | add\_row, add\_case | Add rows to a data frame    | addition | help | NA      | tibble  |
-| <a href=https://glue.tidyverse.org/reference/as_glue.html>as\_glue</a>         | as\_glue            | Coerce object to glue       | NA       | help | NA      | glue    |
+| topic | alias | title | concept | type | keyword | package |
+|:---|:---|:---|:---|:---|:---|:---|
+| <a href=https://tidyverse.r-universe.dev/tibble/doc/manual.html#tribble>tribble</a> | tribble | Row-wise tibble creation | NA | help | NA | tibble |
+| <a href=https://tidyverse.r-universe.dev/glue/doc/manual.html#trim>trim</a> | trim | Trim a character vector | NA | help | NA | glue |
+| <a href=https://tidyverse.r-universe.dev/tibble/doc/manual.html#trunc_mat>trunc_mat</a> | trunc_mat | Legacy printing | NA | help | internal | tibble |
+| <a href=https://tidyverse.r-universe.dev/articles/tibble/types.html>types</a> | types | Column types | NA | vignette | NA | tibble |
+| <a href=https://tidyverse.r-universe.dev/tibble/doc/manual.html#view>view</a> | view | View an object | NA | help | NA | tibble |
+| <a href=https://tidyverse.r-universe.dev/articles/glue/wrappers.html>wrappers</a> | wrappers | How to write a function that wraps glue | NA | vignette | NA | glue |
 
 `DT::datatabe()` also provides a search box. See [Get
 started](https://maurolepore.github.io/dverse/articles/dverse.html).

inst/WORDLIST

@@ -16,3 +16,5 @@ tibble
 tidymodels
 tidyverse
 toyverse
+tribble
+trunc

man/document_universe.Rd

@@ -0,0 +1,8 @@
+# with url_template longer than 2 yields an error
+
+    Code
+      document_universe("base", too_long)
+    Condition
+      Error in `document_universe_impl()`:
+      ! `url_template` must be of length 1 or 2, not 3.
+

tests/testthat/_snaps/document_universe.md

@@ -70,7 +70,7 @@ test_that("with bad `url_template` errors gracefully", {
 })
 
 test_that("vignettes have a reachable link", {
-  # Not using dverse because on developer mode there are no vignettes
+  skip_if_offline()
   withr::local_package("tibble")
 
   template <- "https://{package}.tidyverse.org/reference/{topic}.html"
@@ -83,3 +83,24 @@ test_that("vignettes have a reachable link", {
 
   expect_true(all(is_online(topic)))
 })
+
+test_that("a r-universe template yields the expected vignette topic", {
+  skip_if_offline()
+  withr::local_package("tibble")
+
+  template <- c(
+    manual = "https://tidyverse.r-universe.dev/{package}/doc/manual.html#{topic}",
+    articles = "https://tidyverse.r-universe.dev/articles/{package}/{topic}.html"
+  )
+  out <- document_universe("tibble", url_template = template)
+  url <- extract_url(out[grep("extending", out$topic), ]$topic)
+
+  expected <- "https://tidyverse.r-universe.dev/articles/tibble/extending.html"
+  expect_equal(url, expected)
+  expect_true(is_online(url))
+})
+
+test_that("with url_template longer than 2 yields an error", {
+  too_long <- c("a", "b", "c")
+  expect_snapshot(error = TRUE, document_universe("base", too_long))
+})