Extract lifecycle badges and display on reference index (#2579)

Fixes #2123

NEWS.md

@@ -1,5 +1,6 @@
 # pkgdown (development version)
 
+* `build_reference_index()` now displays lifecycle badges next to the function name (#2123). You can now also use `has_lifecycle()` to select functions by their lifecycle status.
 * `build_articles()` now recognises a new `external-articles` top-level field that allows you to define articles that live in other packages (#2028).
 * New light switch makes it easy for users to switch between light and dark themes for the website (based on work in bslib by @gadenbuie). For now this behaviour is opt-in with `template.light-switch: true` but in the future we may turn it on automatically. See the customization vignette for details (#1696).
 * The search dropdown has been tweaked to look more like the other navbar menu items (#2338).

R/autolink_html.R

@@ -1,6 +1,9 @@
 #' Automatically link references and articles in an HTML page
 #'
-#' Deprecated: please use [downlit::downlit_html_path] instead.
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' Please use [downlit::downlit_html_path] instead.
 #'
 #' @param input,output Input and output paths for HTML file
 #' @param local_packages A named character vector providing relative paths

R/build-reference.R

@@ -80,6 +80,8 @@
 #'    captured by `has_concepts()`.
 #' * Topics from other installed packages, e.g. `rlang::is_installed()` (function name)
 #'  or `sass::font_face` (topic name).
+#' * `has_lifecycle("deprecated")` will select all topics with lifecycle 
+#'   deprecated.
 #'
 #' All functions (except for `has_keywords()`) automatically exclude internal
 #' topics (i.e. those with `\keyword{internal}`). You can choose to include

R/package.R

@@ -217,6 +217,7 @@ package_topics <- function(path = ".", package = "pkgdown") {
   keywords <- unname(purrr::map(rd, extract_tag, "tag_keyword"))
   internal <- purrr::map_lgl(keywords, ~ "internal" %in% .)
   source <- purrr::map(rd, extract_source)
+  lifecycle <- unname(purrr::map(rd, extract_lifecycle))
 
   file_in <- names(rd)
   file_out <- rd_output_path(file_in)
@@ -234,7 +235,8 @@ package_topics <- function(path = ".", package = "pkgdown") {
     source = source,
     keywords = keywords,
     concepts = concepts,
-    internal = internal
+    internal = internal,
+    lifecycle = lifecycle
   )
 }
 
@@ -285,6 +287,43 @@ extract_source <- function(x) {
   regmatches(text, m)[[1]]
 }
 
+extract_lifecycle <- function(x) {
+  fig <- extract_figure(x)
+  if (!is.null(fig) && length(fig) > 0 && length(fig[[1]]) > 0) {
+    path <- as.character(fig[[1]][[1]])  
+    if (grepl("lifecycle", path)) {
+      name <- gsub("lifecycle-", "", path)
+      name <- path_ext_remove(name)
+
+      # Translate the most common lifecylce names
+      name <- switch(name,
+        deprecated = tr_("deprecated"),
+        superseded = tr_("superseded"),
+        experimental = tr_("experimental"),
+        stable = tr_("stable"),
+        name
+      )
+
+      return(name)
+    }
+  }
+  NULL
+}
+
+extract_figure <- function(elements) {
+  for (element in elements) {
+    if (inherits(element, "tag_figure")) {
+      return(element)
+    } else if (inherits(element, "tag")) {
+      child <- extract_figure(element)
+      if (!is.null(child)) {
+        return(child)
+      }
+    }
+  }
+  NULL
+}
+
 # Vignettes ---------------------------------------------------------------
 
 package_vignettes <- function(path = ".") {

R/topics-external.R

@@ -21,7 +21,8 @@ ext_topics <- function(match_strings) {
     source = NA_character_,
     keywords = list(character()), # used for has_keyword()
     concepts = list(character()), # used for has_concept()
-    internal = FALSE
+    internal = FALSE,
+    lifecycle = list(NULL)        # used for has_lifecycle
   )
 }
 

R/topics.R

@@ -132,6 +132,10 @@ match_env <- function(topics) {
     check_character(x)
     which(purrr::map_lgl(topics$keywords, ~ any(. %in% x)))
   }
+  fns$has_lifecycle <- function(x) {
+    check_string(x)
+    which(purrr::map_lgl(topics$lifecycle, ~ any(. %in% x)))
+  }
   fns$has_concept <- function(x, internal = FALSE) {
     check_string(x)
     check_bool(internal)
@@ -224,6 +228,7 @@ section_topics <- function(match_strings, topics, src_path) {
     name = selected$name,
     path = selected$file_out,
     title = selected$title,
+    lifecycle = selected$lifecycle,
     aliases = purrr::map2(selected$funs, selected$alias, ~ if (length(.x) > 0) .x else .y),
     icon = find_icons(selected$alias, path(src_path, "icons"))
   )

inst/BS5/assets/pkgdown.scss

@@ -345,6 +345,16 @@ a[href='#main'] {
   z-index: 2000;
 }
 
+.lifecycle {
+  color: var(--bs-secondary-color);
+  background-color: var(--bs-secondary-bg);  // backup just in case we don't know the name
+  border-radius: 5px;
+}
+.lifecycle-stable       { background-color: rgb(16, 128, 1);  color: var(--bs-white);}
+.lifecycle-superseded   { background-color: rgb(7, 64, 128);  color: var(--bs-white);}
+.lifecycle-experimental, 
+.lifecycle-deprecated   { background-color: rgb(253, 128, 8); color: var(--bs-black);}
+
 /* Footnotes ---------------------------------------------------------------- */
 
 a.footnote-ref {

inst/BS5/templates/content-reference-index.html

@@ -14,6 +14,7 @@ <h1>{{{pagetitle}}}</h1>
         <dt>
           {{#has_icons}}{{#icon}}<a class="icon" href="{{path}}"><img src="icons/{{{.}}}" alt=""/></a>{{/icon}}{{/has_icons}}
           {{#aliases}}<code><a href="{{path}}">{{{.}}}</a></code> {{/aliases}}
+          {{#lifecycle}}<span class="badge lifecycle lifecycle-{{.}}">{{.}}</span>{{/lifecycle}}
         </dt>
         <dd>{{{title}}}</dd>
       </dl>{{/topics}}

pkgdown/_pkgdown.yml

@@ -83,6 +83,10 @@ reference:
   contents:
   - starts_with("test", internal = TRUE)
 
+- title: Deprecated functions
+  contents:
+  - has_lifecycle("deprecated")
+
 redirects:
 - ["articles/search.html", "reference/build_search.html"]