Merge commit 'ac1a5ce3b703482a53226eeb49f54cd5eaac87ba'

.github/workflows/pkgdown.yaml

@@ -24,7 +24,9 @@ jobs:
 
       - uses: r-lib/actions/setup-pandoc@v2
 
-      - uses: r-lib/actions/setup-r@v2
+     - uses: r-lib/actions/setup-tinytex@v2
+
+     - uses: r-lib/actions/setup-r@v2
         with:
           use-public-rspm: true
 

NEWS.md

@@ -4,6 +4,14 @@
   * No longer support IE9 or earlier
   * Strip trailing whitespace
   * Label `<nav>`s and improve navbar html.
+* `build_home_index()` now renders math if you use it in your home page (#2263).
+* `build_home()` now correctly escapes special HTML characters in the bibtex citation (#2022).
+* BS5 templates no longer include empty link to logo when none exists (#2536).
+* `build_articles()` now reports if you are missing alt-text for any images (#2357).
+* `check_pkgdown()` and `pkgdown_sitrep()` have been unified so that they both report on the same problems. They now only differ in the style of their output: `pkgdown_sitrep()` reports whether each category is ok or not ok, while `check_pkgdown()` errors on the first issue (#2463).
+* `build_site()` automatically runs `pkgdown_sitrep()` at the start of the process (#2380).
+* New `vignette("accessibility")` describes what manual tasks you need to perform to make your site as accessible as possible (#2344).
+* `build_reference()` now automatically translates `--`, `---`, ``` `` ```, and `''` to their unicode equivalents (#2530).
 * Tweaked navbar display on mobile so that long titles in drop downs (e.g. article titles) are now wrapped, and the search input spans the full width (#2512).
 * `build_reference()` now supports `\Sexpr[results=verbatim]` (@bastistician, #2510).
 * `build_home()` no longer checks if the README is missing any images. This check is now performed in `build_site()`, after `build_articles()` so you can refer to images created by vignettes with warnings (#2194).

R/build-articles.R

@@ -381,9 +381,9 @@ data_articles_index <- function(pkg = ".") {
   pkg <- as_pkgdown(pkg)
 
   meta <- pkg$meta$articles %||% default_articles_index(pkg)
-  sections <- meta %>%
-    purrr::map(data_articles_index_section, pkg = pkg) %>%
-    purrr::compact()
+  sections <- unwrap_purrr_error(meta %>%
+    purrr::imap(data_articles_index_section, pkg = pkg) %>%
+    purrr::compact())
 
   # Check for unlisted vignettes
   listed <- sections %>%
@@ -413,13 +413,9 @@ data_articles_index <- function(pkg = ".") {
   ))
 }
 
-data_articles_index_section <- function(section, pkg) {
-  if (!set_contains(names(section), c("title", "contents"))) {
-    cli::cli_abort(
-      "Section must have components {.field title}, {.field contents}",
-      call = caller_env()
-    )
-  }
+data_articles_index_section <- function(section, index, pkg) {
+  id <- section$title %||% section$subtitle %||% index
+  check_contents(section$contents, id, pkg, quote(build_articles()))
 
   # Match topics against any aliases
   in_section <- select_vignettes(section$contents, pkg$vignettes)

R/build-favicons.R

@@ -42,7 +42,7 @@ build_favicons <- function(pkg = ".", overwrite = FALSE) {
     i = "Building favicons with {.url https://realfavicongenerator.net} ..."
   ))
 
-  logo <- readBin(logo_path, what = "raw", n = fs::file_info(logo_path)$size)
+  logo <- readBin(logo_path, what = "raw", n = file_info(logo_path)$size)
 
   json_request <- list(
     "favicon_generation" = list(

R/build-home-index.R

@@ -61,11 +61,11 @@ data_home_sidebar <- function(pkg = ".", call = caller_env()) {
   if (isFALSE(pkg$meta$home$sidebar))
     return(pkg$meta$home$sidebar)
 
-  html_path <- file.path(pkg$src_path, pkg$meta$home$sidebar$html)
+  html_path <- path(pkg$src_path, pkg$meta$home$sidebar$html)
 
   if (length(html_path)) {
     if (!file.exists(html_path)) {
-      rel_html_path <- fs::path_rel(html_path, pkg$src_path)
+      rel_html_path <- path_rel(html_path, pkg$src_path)
       config_abort(
         pkg,
         "{.field home.sidebar.html} specifies a file that doesn't exist ({.file {rel_html_path}}).",

R/build-home-md.R

@@ -20,7 +20,7 @@ package_mds <- function(path, in_dev = FALSE) {
 
   # Do not build 404 page if in-dev
   if (in_dev) {
-    mds <- mds[fs::path_file(mds) != "404.md"]
+    mds <- mds[path_file(mds) != "404.md"]
   }
 
   # Remove files that don't need to be rendered
@@ -29,7 +29,7 @@ package_mds <- function(path, in_dev = FALSE) {
     "pull_request_template.md",
     "cran-comments.md"
   )
-  mds <- mds[!fs::path_file(mds) %in% no_render]
+  mds <- mds[!path_file(mds) %in% no_render]
 
   unname(mds)
 }
@@ -45,7 +45,7 @@ render_md <- function(pkg, filename) {
       pagetitle = attr(body, "title"),
       body = body,
       filename = filename,
-      source = repo_source(pkg, fs::path_rel(filename, pkg$src_path))
+      source = repo_source(pkg, path_rel(filename, pkg$src_path))
     ),
     path = path
   )

R/build-logo.R

@@ -34,5 +34,5 @@ logo_path <- function(pkg, depth) {
     return()
   }
 
-  paste0(up_path(depth), fs::path_file(path))
+  paste0(up_path(depth), path_file(path))
 }

R/build-reference-index.R

@@ -50,7 +50,7 @@ data_reference_index_rows <- function(section, index, pkg) {
 
   if (has_name(section, "contents")) {
     id <- section$title %||% section$subtitle %||% index
-    check_contents(section$contents, id, pkg)
+    check_contents(section$contents, id, pkg, quote(build_reference_index()))
     topics <- section_topics(section$contents, pkg$topics, pkg$src_path)
 
     names <- topics$name
@@ -67,9 +67,7 @@ data_reference_index_rows <- function(section, index, pkg) {
   purrr::compact(rows)
 }
 
-check_contents <- function(contents, id, pkg) {
-  call <- quote(build_reference_index())
-
+check_contents <- function(contents, id, pkg, call = caller_env()) {
   if (length(contents) == 0) {
     config_abort(
       pkg,

R/build-reference.R

@@ -310,13 +310,13 @@ build_reference_topic <- function(topic,
     deps <- purrr::map(
       deps,
       htmltools::copyDependencyToDir,
-      outputDir = file.path(pkg$dst_path, "reference", "libs"),
+      outputDir = path(pkg$dst_path, "reference", "libs"),
       mustWork = FALSE
     )
     deps <- purrr::map(
       deps,
       htmltools::makeDependencyRelative,
-      basepath = file.path(pkg$dst_path, "reference"),
+      basepath = path(pkg$dst_path, "reference"),
       mustWork = FALSE
     )
     data$dependencies <- htmltools::renderDependencies(deps, c("file", "href"))

R/build-search-docs.R

@@ -96,7 +96,7 @@ build_search <- function(pkg = ".",
   search_index <- build_search_index(pkg)
   jsonlite::write_json(
     search_index,
-    file.path(pkg$dst_path, "search.json"),
+    path(pkg$dst_path, "search.json"),
     auto_unbox = TRUE
   )
 }
@@ -127,7 +127,7 @@ build_search_index <- function(pkg) {
 }
 
 news_search_index <- function(path, pkg) {
-  html <- xml2::read_html(file.path(pkg$dst_path, path), encoding = "UTF-8")
+  html <- xml2::read_html(path(pkg$dst_path, path), encoding = "UTF-8")
 
   # Get contents minus logo
   node <- xml2::xml_find_all(html, ".//main")
@@ -147,7 +147,7 @@ news_search_index <- function(path, pkg) {
 }
 
 file_search_index <- function(path, pkg) {
-  html <- xml2::read_html(file.path(pkg$dst_path, path), encoding = "UTF-8")
+  html <- xml2::read_html(path(pkg$dst_path, path), encoding = "UTF-8")
   # Get page title
   title <- xml2::xml_find_first(html, ".//meta[@property='og:title']") %>%
     xml2::xml_attr("content")
@@ -171,11 +171,11 @@ file_search_index <- function(path, pkg) {
 }
 # Directory parts (where in the site)
 get_dir <- function(path) {
-  dir <- fs::path_dir(path)
+  dir <- path_dir(path)
   if (dir == ".") {
     return("")
   }
-  paste(capitalise(unlist(fs::path_split(dir))), collapse = " > ")
+  paste(capitalise(unlist(path_split(dir))), collapse = " > ")
 }
 # Headings (where in the page)
 get_headings <- function(section, depth) {
@@ -303,10 +303,10 @@ capitalise <- function(string) {
 }
 
 get_site_paths <- function(pkg) {
-  paths <- fs::dir_ls(pkg$dst_path, glob = "*.html", recurse = TRUE)
-  paths_rel <- fs::path_rel(paths, pkg$dst_path)
+  paths <- dir_ls(pkg$dst_path, glob = "*.html", recurse = TRUE)
+  paths_rel <- path_rel(paths, pkg$dst_path)
 
   # do not include dev package website in search index / sitemap
   dev_destination <- meta_development(pkg$meta, pkg$version)$destination
-  paths_rel[!fs::path_has_parent(paths_rel, "dev")]
+  paths_rel[!path_has_parent(paths_rel, "dev")]
 }

R/build.R

@@ -443,6 +443,8 @@ build_site_local <- function(pkg = ".",
   cli::cli_inform("Reading from: {src_path(path_abs(pkg$src_path))}")
   cli::cli_inform("Writing to:   {dst_path(path_abs(pkg$dst_path))}")
 
+  pkgdown_sitrep(pkg)
+
   init_site(pkg)
 
   build_home(pkg, override = override, preview = FALSE)

R/check-built.R

@@ -0,0 +1,38 @@
+
+check_built_site <- function(pkg = ".") {
+  pkg <- as_pkgdown(pkg)
+
+  cli::cli_rule("Checking for problems")
+  index_path <- path_index(pkg)
+  if (!is.null(index_path)) {
+    check_missing_images(pkg, index_path, "index.html")
+  }
+}
+
+check_missing_images <- function(pkg, src_path, dst_path) {
+  html <- xml2::read_html(path(pkg$dst_path, dst_path), encoding = "UTF-8")
+  img <- xml2::xml_find_all(html, ".//img")
+  src <- xml2::xml_attr(img, "src")
+
+  rel_src <- src[xml2::url_parse(src)$scheme == ""]
+  rel_path <- path_norm(path(path_dir(dst_path), rel_src))
+  exists <- file_exists(path(pkg$dst_path, rel_path))
+
+  if (any(!exists)) {
+    paths <- rel_src[!exists]
+    cli::cli_inform(c(
+      "Missing images in {.file {path_rel(src_path, pkg$src_path)}}: {.file {paths}}",
+      i = "pkgdown can only use images in {.file man/figures} and {.file vignettes}"
+    ))
+  }
+
+  alt <- xml2::xml_attr(img, "alt")
+  if (anyNA(alt)) {
+    problems <- src[is.na(alt)]
+    problems[grepl("^data:image", problems)] <- "<base64 encoded image>"
+    cli::cli_inform(c(
+      x = "Missing alt-text in {.file {path_rel(src_path, pkg$src_path)}}",
+      set_names(problems, "*")
+    ))
+  }
+}

R/check.R

@@ -1,50 +1,87 @@
 #' Check `_pkgdown.yml`
 #'
 #' @description
-#' Check that your `_pkgdown.yml` is valid without building the whole
-#' site. Currently this:
+#' This pair of functions checks that your `_pkgdown.yml` is valid without 
+#' building the whole site. `check_pkgdown()` errors at the first problem;
+#' `pkgdown_sitrep()` reports the status of all checks.
+#' 
+#' Currently they check that:
 #'
-#' * Checks the reference and article indexes to ensure that pkgdown can
-#'   read them, and that every documentation topic and vignette/article is 
-#'   included in the index.
+#' * There's a `url` in the pkgdown configuration, which is also recorded
+#'   in the `URL` field of the `DESCRIPTION`.
 #'
-#' * Validates any opengraph metadata that you might have supplied
+#' * All opengraph metadata is valid.
 #'
+#' * All reference topics are included in the index.
+#'
+#' * All articles/vignettes are included in the index.
+#
 #' @export
 #' @inheritParams as_pkgdown
 check_pkgdown <- function(pkg = ".") {
   pkg <- as_pkgdown(pkg)
 
+  check_urls(pkg)
   data_open_graph(pkg)
   data_articles_index(pkg)
   data_reference_index(pkg)
 
   cli::cli_inform(c("v" = "No problems found."))
 }
 
-check_built_site <- function(pkg = ".") {
+#' @export
+#' @rdname check_pkgdown
+pkgdown_sitrep <- function(pkg = ".") {
+  cli::cli_rule("Sitrep")
+
   pkg <- as_pkgdown(pkg)
+  error_to_sitrep("URLs", check_urls(pkg))
+  error_to_sitrep("Open graph metadata", data_open_graph(pkg))
+  error_to_sitrep("Articles metadata", data_articles_index(pkg))
+  error_to_sitrep("Reference metadata", data_reference_index(pkg))
+}
 
-  cli::cli_rule("Checking for problems")
-  index_path <- path_index(pkg)
-  if (!is.null(index_path)) {
-    check_missing_images(pkg, index_path, "index.html")
-  }
+error_to_sitrep <- function(title, code) {
+  tryCatch(
+    {
+      code
+      cli::cli_inform(c("v" = "{title} ok."))
+    },
+    rlang_error = function(e) {
+      bullets <- c(cnd_header(e), cnd_body(e))
+      cli::cli_inform(c(x = "{title} not ok.", set_names(bullets, " ")))
+    }
+  )
+  invisible()
 }
 
-check_missing_images <- function(pkg, src_path, dst_path) {
-  html <- xml2::read_html(path(pkg$dst_path, dst_path), encoding = "UTF-8")
-  src <- xml2::xml_attr(xml2::xml_find_all(html, ".//img"), "src")
+check_urls <- function(pkg = ".", call = caller_env()) {
+  pkg <- as_pkgdown(pkg)
+  details <- c(i = "See details in {.vignette pkgdown::metadata}.")
+
+  if (identical(pkg$meta, list())) {
+    cli::cli_abort(
+      c("No {.path _pkgdown.yml} found.", details),
+      call = call
+    )
+  }
 
-  rel_src <- src[xml2::url_parse(src)$scheme == ""]
-  rel_path <- fs::path_norm(path(fs::path_dir(dst_path), rel_src))
-  exists <- fs::file_exists(path(pkg$dst_path, rel_path))
+  url <- pkg$meta[["url"]]
 
-  if (any(!exists)) {
-    paths <- rel_src[!exists]
-    cli::cli_warn(c(
-      "Missing images in {.file {path_rel(src_path, pkg$src_path)}}: {.file {paths}}",
-      i = "pkgdown can only use images in {.file man/figures} and {.file vignettes}"
-    ))
+  if (is.null(url)) {
+    cli::cli_abort(
+      c("{config_path(pkg)} lacks {.field url}.", details),
+      call = call
+    )
+  } else {
+    desc_urls <- pkg$desc$get_urls()
+    desc_urls <- sub("/$", "", desc_urls)
+
+    if (!pkg$meta[["url"]] %in% desc_urls) {
+      cli::cli_abort(
+        c("{.file DESCRIPTION} {.field URL} lacks package url ({url}).", details),
+        call = call
+      )
+    } 
   }
 }

R/config.R

@@ -132,5 +132,5 @@ config_path <- function(pkg) {
   if (is.null(config)) {
     cli::cli_abort("Can't find {.file _pkgdown.yml}.", .internal = TRUE)
   }
-  cli::style_hyperlink(fs::path_file(config), paste0("file://", config))
+  cli::style_hyperlink(path_file(config), paste0("file://", config))
 }

R/context.R

@@ -68,7 +68,7 @@ context_set_scoped <- function(name, value, scope = parent.frame()) {
 
 article_index <- function(pkg) {
   set_names(
-    fs::path_rel(pkg$vignettes$file_out, "articles"),
+    path_rel(pkg$vignettes$file_out, "articles"),
     pkg$vignettes$name
   )
 }