Polish docs of document_universe()

R/document_universe.R

@@ -57,38 +57,56 @@ vignettes_template <- function(template) {
 #' @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.
-#'
+#'   The template may have lengh 1 or 2:
+#'   * If the template is a vector has length 1, the template should point to the
+#'   manual (a.k.a. "reference" or "index"), i.e. the online version of the help
+#'   files that you can otherwise access locally with `?`, e.g.:
+#'   ```r
+#'   "https://{package}.tidyverse.org/reference/{topic}.html"
+#'   ```
+#'   In this case, the template for vignettes is automatically constructed by
+#'   replacing `/reference/` with `/articles/`, e.g.:
+#'   ```r
+#'   "https://{package}.tidyverse.org/articles/{topic}.html"
+#'   ```
+#'   If this is invalid, then you'll need to provide a vector of length 2.
+#'   * If the template is a vector has length 2, the first element should point to the manual
+#'   (see above), and the second element should point to vignettes, e.g.:
+#'   ```r
+#'   c(
+#'    "https://{package}.tidyverse.org/reference/{topic}.html",
+#'    "https://{package}.tidyverse.org/articles/{topic}.html"
+#'   )
+#'   ```
 #' @return A data frame.
 #'
 #' @export
 #' @examples
+#' # Pretend this is the universe we want to document
 #' library(glue)
 #' library(tibble)
 #'
 #' universe <- c("glue", "tibble")
+#'
 #' document_universe(universe)
 #'
-#' # Assuming vignettes can be found at */articles/* rather than */reference/*
-#' manual <- "https://{package}.tidyverse.org/reference/{topic}.html"
-#' document_universe(universe, url_template = manual)
+#' # Adding links the online manual and vignettes
+#' template <- "https://{package}.tidyverse.org/reference/{topic}.html"
+#' document_universe(universe, template)
 #'
 #' # Adding an explicit template for vignettes
-#' vignettes <- "https://{package}.tidyverse.org/articles/{topic}.html"
-#' document_universe(universe, c(manual, vignettes))
+#' template <- c(
+#'  "https://{package}.tidyverse.org/reference/{topic}.html",
+#'  "https://{package}.tidyverse.org/articles/{topic}.html"
+#' )
+#' document_universe(universe, template)
 #'
 #' # Works beyond GitHub Pages, e.g. on r-universe
-#' manual <- "https://tidyverse.r-universe.dev/{package}/doc/manual.html#{topic}"
-#' vignettes <- "https://tidyverse.r-universe.dev/articles/{package}/{topic}.html"
-#' document_universe(universe, c(manual, vignettes))
+#' template <- c(
+#'   "https://tidyverse.r-universe.dev/{package}/doc/manual.html#{topic}",
+#'   "https://tidyverse.r-universe.dev/articles/{package}/{topic}.html"
+#' )
+#' document_universe(universe, template)
 document_universe <- function(x, url_template = NULL) {
   out <- document_universe_impl(x = x, url_template = url_template)
   tibble::as_tibble(out)

README.Rmd

@@ -72,10 +72,9 @@ using [pkgdown](https://pkgdown.r-lib.org/).
 ## Example
 
 * `document_universe()` creates a data frame with documentation metadata of one or
-more packages.
-* `url_template` can take different templates for the manual and vignettes.
-* `knitr::kable()` turns the URLs into clickable links. `DT::datatabe()` also
-provides a search box.
+more packages, i.e. the universe.
+* You can then turn the URLs into clickable links with e.g. `knitr::kable()` or
+`DT::datatabe()` (which also provides a search box).
 
 ```{r}
 library(dverse)
@@ -88,17 +87,6 @@ template <- "https://{package}.tidyverse.org/reference/{topic}.html"
 docs <- document_universe(packages, template)
 
 docs
-```
-
-```{r}
-#| eval: !r on_ci
-#| echo: !r on_ci
-DT::datatable(docs, escape = FALSE)
-```
 
-```{r}
-#| eval: !r on_ci
-#| echo: !r on_ci
 knitr::kable(tail(docs))
 ```
-

README.md

@@ -66,11 +66,10 @@ website, for example using [pkgdown](https://pkgdown.r-lib.org/).
 ## Example
 
 - `document_universe()` creates a data frame with documentation metadata
-  of one or more packages.
-- `url_template` can take different templates for the manual and
-  vignettes.
-- `knitr::kable()` turns the URLs into clickable links. `DT::datatabe()`
-  also provides a search box.
+  of one or more packages, i.e. the universe.
+- You can then turn the URLs into clickable links with
+  e.g. `knitr::kable()` or `DT::datatabe()` (which also provides a
+  search box).
 
 ``` r
 library(dverse)
@@ -97,4 +96,15 @@ docs
 #>  9 <a href=https://glue.tidyverse.org… engi… Cust… <NA>    vign… <NA>    glue   
 #> 10 <a href=https://tibble.tidyverse.o… exte… Exte… <NA>    vign… <NA>    tibble 
 #> # ℹ 36 more rows
+
+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 |