From 2f4a23468cb2b4e0b2acfda7ae44d3ead45ff25c Mon Sep 17 00:00:00 2001 From: Mauro Lepore Date: Sun, 8 Jun 2025 08:16:50 -0700 Subject: [PATCH 1/4] Even simpler README --- README.Rmd | 18 +++--------------- README.md | 20 +++++++++++++++----- 2 files changed, 18 insertions(+), 20 deletions(-) diff --git a/README.Rmd b/README.Rmd index 614433b..82fa36d 100644 --- a/README.Rmd +++ b/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)) ``` - diff --git a/README.md b/README.md index b5ecb74..591cf6b 100644 --- a/README.md +++ b/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 vign… glue #> 10 vign… tibble #> # ℹ 36 more rows + +knitr::kable(tail(docs)) ``` + +| topic | alias | title | concept | type | keyword | package | +|:---|:---|:---|:---|:---|:---|:---| +| tribble | tribble | Row-wise tibble creation | NA | help | NA | tibble | +| trim | trim | Trim a character vector | NA | help | NA | glue | +| trunc_mat | trunc_mat | Legacy printing | NA | help | internal | tibble | +| types | types | Column types | NA | vignette | NA | tibble | +| view | view | View an object | NA | help | NA | tibble | +| wrappers | wrappers | How to write a function that wraps glue | NA | vignette | NA | glue | From 3883a8ef908670fb14bb6c03e4b722eeaf0ba70f Mon Sep 17 00:00:00 2001 From: Mauro Lepore Date: Sun, 8 Jun 2025 12:30:48 -0700 Subject: [PATCH 2/4] Polish docs --- R/document_universe.R | 54 ++++++++++++++++++++++++------------ man/document_universe.Rd | 59 ++++++++++++++++++++++++++++------------ 2 files changed, 78 insertions(+), 35 deletions(-) diff --git a/R/document_universe.R b/R/document_universe.R index 372738d..38a5327 100644 --- a/R/document_universe.R +++ b/R/document_universe.R @@ -57,16 +57,30 @@ 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 @@ -75,20 +89,26 @@ vignettes_template <- function(template) { #' 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) diff --git a/man/document_universe.Rd b/man/document_universe.Rd index e6dbdfc..689445b 100644 --- a/man/document_universe.Rd +++ b/man/document_universe.Rd @@ -12,17 +12,34 @@ document_universe(x, url_template = NULL) \item{url_template}{Character. A template to generate links to documentation, using the syntax of \code{glue::glue()} to indicate where to insert the values from the columns \code{package} and \code{topic}. + +The template may have lengh 1 or 2: +\itemize{ +\item 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 \verb{?}, e.g.: +} + +\if{html}{\out{
}}\preformatted{"https://\{package\}.tidyverse.org/reference/\{topic\}.html" +}\if{html}{\out{
}} + +In this case, the template for vignettes is automatically constructed by +replacing \verb{/reference/} with \verb{/articles/}, e.g.: + +\if{html}{\out{
}}\preformatted{"https://\{package\}.tidyverse.org/articles/\{topic\}.html" +}\if{html}{\out{
}} + +If this is invalid, then you'll need to provide a vector of length 2. \itemize{ -\item If the vector has length 1, we assume it's for the manual (i.e. what you -can access with \verb{?}), e.g.: -\code{"https://maurolepore.github.io/{package}/reference/{topic}.html"}. The -template for vignettes will be automatically constructed by replacing -/reference/ with /articles/, e.g. -\code{"https://maurolepore.github.io/{package}/articles/{topic}.html"}. If this -is invalid, then you'll need to provide a vector of length 2. -\item If the vector has length 2, we assume the first element is for the -manual and the second element is for vignettes. -}} +\item 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.: +} + +\if{html}{\out{
}}\preformatted{c( + "https://\{package\}.tidyverse.org/reference/\{topic\}.html", + "https://\{package\}.tidyverse.org/articles/\{topic\}.html" +) +}\if{html}{\out{
}}} } \value{ A data frame. @@ -38,18 +55,24 @@ 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) } From ede031310a79cf09c2d8875c9d97b527638c14ad Mon Sep 17 00:00:00 2001 From: Mauro Lepore Date: Sun, 8 Jun 2025 12:34:02 -0700 Subject: [PATCH 3/4] Refactor --- R/document_universe.R | 3 --- man/document_universe.Rd | 1 - 2 files changed, 4 deletions(-) diff --git a/R/document_universe.R b/R/document_universe.R index 38a5327..d869038 100644 --- a/R/document_universe.R +++ b/R/document_universe.R @@ -57,9 +57,7 @@ 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`. -#' #' 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.: @@ -72,7 +70,6 @@ vignettes_template <- function(template) { #' "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 diff --git a/man/document_universe.Rd b/man/document_universe.Rd index 689445b..d2aae1d 100644 --- a/man/document_universe.Rd +++ b/man/document_universe.Rd @@ -12,7 +12,6 @@ document_universe(x, url_template = NULL) \item{url_template}{Character. A template to generate links to documentation, using the syntax of \code{glue::glue()} to indicate where to insert the values from the columns \code{package} and \code{topic}. - The template may have lengh 1 or 2: \itemize{ \item If the template is a vector has length 1, the template should point to the From a8e757e1dea645dd08a3711e9cb1b499d2f21283 Mon Sep 17 00:00:00 2001 From: Mauro Lepore Date: Sun, 8 Jun 2025 12:40:07 -0700 Subject: [PATCH 4/4] Comment --- R/document_universe.R | 1 + man/document_universe.Rd | 1 + 2 files changed, 2 insertions(+) diff --git a/R/document_universe.R b/R/document_universe.R index d869038..e508e0e 100644 --- a/R/document_universe.R +++ b/R/document_universe.R @@ -82,6 +82,7 @@ vignettes_template <- function(template) { #' #' @export #' @examples +#' # Pretend this is the universe we want to document #' library(glue) #' library(tibble) #' diff --git a/man/document_universe.Rd b/man/document_universe.Rd index d2aae1d..e0a54b7 100644 --- a/man/document_universe.Rd +++ b/man/document_universe.Rd @@ -50,6 +50,7 @@ to easily create a universe-wide reference for the pkgdown website of your meta-package. } \examples{ +# Pretend this is the universe we want to document library(glue) library(tibble)