Unify sitrep and check

* Introduce new `check_urls()` function that reports on url problems with errors and call it in `check_pkgdown()`
* `pkgdown_sitrep()` now calls the same functions as `check_pkgdown()` but wrapped in a helper to convert errors to messages
* `check_built()` is a separate concern so it's moved to a separate file

Fixes #2463. Fixes #2380.

NEWS.md

@@ -1,5 +1,7 @@
 # pkgdown (development version)
 
+* `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).
 * `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).
 * `build_home()` now includes the contents of `inst/AUTHORS` on the authors page (#2506).
 * If you put a dropdown menu (e.g. articles) on the right hand side of the navbar, it will now be right aligned. This makes longer titles more likely to stay on the page (#2421).

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,27 @@
+
+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")
+  src <- xml2::xml_attr(xml2::xml_find_all(html, ".//img"), "src")
+
+  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))
+
+  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}"
+    ))
+  }
+}

R/check.R

@@ -1,50 +1,84 @@
 #' 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 = ".") {
-  pkg <- as_pkgdown(pkg)
+#' @export
+#' @rdname check_pkgdown
+pkgdown_sitrep <- function(pkg = ".") {
+  cli::cli_rule("Sitrep")
 
-  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("Package structure", 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))
 }
 
-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")
+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()
+}
 
-  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))
+check_urls <- function(pkg = ".", call = caller_env()) {
+  pkg <- as_pkgdown(pkg)
+  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(
+        x = "{config_path(pkg)} lacks {.field url}.",
+        i = "See details in {.vignette pkgdown::metadata}."
+      ),
+      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(
+          x = "{.file DESCRIPTION} {.field URL} lacks package url ({url}).",
+          i = "See details in {.vignette pkgdown::metadata}."
+        ),
+        call = call
+      )
+    } 
   }
 }

pkgdown/_pkgdown.yml

@@ -1,4 +1,3 @@
-url: https://pkgdown.r-lib.org
 
 home:
   title: Build websites for R packages
@@ -34,7 +33,6 @@ articles:
   contents:
   - customise
   - linking
-  - search
   - metadata
 
 - title: Advanced techniques

tests/testthat/_snaps/check-built.md

@@ -0,0 +1,11 @@
+# warn about missing images in readme
+
+    Code
+      check_built_site(pkg)
+    Message
+      -- Checking for problems -------------------------------------------------------
+    Condition
+      Warning:
+      Missing images in 'README.md': 'articles/kitten.jpg'
+      i pkgdown can only use images in 'man/figures' and 'vignettes'
+

tests/testthat/_snaps/check.md

@@ -1,37 +1,60 @@
-# fails if reference index incomplete
+# sitrep reports all problems
 
     Code
-      check_pkgdown(pkg)
-    Condition
-      Error in `check_pkgdown()`:
-      ! 1 topic missing from index: "?".
-      i Either use `@keywords internal` to drop from index, or
-      i Edit _pkgdown.yml to fix the problem.
-
-# fails if article index incomplete
+      pkgdown_sitrep(pkg)
+    Message
+      -- Sitrep ----------------------------------------------------------------------
+      v Package structure ok.
+      x URLs not ok.
+        'DESCRIPTION' URL lacks package url (http://test.org).
+        See details in `vignette(pkgdown::metadata)`.
+      v Open graph metadata ok.
+      v Articles metadata ok.
+      x Reference metadata not ok.
+        1 topic missing from index: "?".
+        Either use `@keywords internal` to drop from index, or
+        Edit _pkgdown.yml to fix the problem.
+
+# checks fails on first problem
 
     Code
       check_pkgdown(pkg)
     Condition
       Error in `check_pkgdown()`:
-      ! 2 vignettes missing from index: "articles/nested" and "width".
-      i Edit _pkgdown.yml to fix the problem.
+      x 'DESCRIPTION' URL lacks package url (http://test.org).
+      i See details in `vignette(pkgdown::metadata)`.
 
-# informs if everything is ok
+# both inform if everything is ok
 
+    Code
+      pkgdown_sitrep(pkg)
+    Message
+      -- Sitrep ----------------------------------------------------------------------
+      v Package structure ok.
+      v URLs ok.
+      v Open graph metadata ok.
+      v Articles metadata ok.
+      v Reference metadata ok.
     Code
       check_pkgdown(pkg)
     Message
       v No problems found.
 
-# warn about missing images in readme
+# check_urls reports problems
 
     Code
-      check_built_site(pkg)
-    Message
-      -- Checking for problems -------------------------------------------------------
+      check_urls(pkg)
+    Condition
+      Error:
+      x _pkgdown.yml lacks url.
+      i See details in `vignette(pkgdown::metadata)`.
+
+---
+
+    Code
+      check_urls(pkg)
     Condition
-      Warning:
-      Missing images in 'README.md': 'articles/kitten.jpg'
-      i pkgdown can only use images in 'man/figures' and 'vignettes'
+      Error:
+      x 'DESCRIPTION' URL lacks package url (https://testpackage.r-lib.org).
+      i See details in `vignette(pkgdown::metadata)`.