From 9e6cafde9eea7e4f124c7505f24654a9538b61b6 Mon Sep 17 00:00:00 2001
From: olivroy <52606734+olivroy@users.noreply.github.com>
Date: Tue, 2 Apr 2024 09:54:10 -0400
Subject: [PATCH] Add advice to use `usethis::edit_pkgdown_config()` (#2419)

---
 DESCRIPTION                                   |  1 +
 R/build-favicons.R                            | 11 +++++---
 R/build-home-index.R                          | 15 ++++++-----
 R/development.R                               |  6 ++---
 R/sitrep.R                                    | 12 +++++----
 R/theme.R                                     |  2 +-
 R/topics.R                                    | 12 ++++++---
 R/utils-yaml.R                                | 17 +++++++-----
 tests/testthat/_snaps/build-favicons.md       |  9 +++++++
 tests/testthat/_snaps/build-home-index.md     | 24 +++++++++--------
 tests/testthat/_snaps/build-redirects.md      |  2 +-
 .../testthat/_snaps/build-reference-index.md  |  4 +--
 tests/testthat/_snaps/development.md          |  3 ++-
 tests/testthat/_snaps/package.md              |  2 +-
 tests/testthat/_snaps/render.md               |  2 +-
 tests/testthat/_snaps/sitrep.md               |  9 ++++---
 tests/testthat/_snaps/topics.md               | 27 ++++++++++++-------
 tests/testthat/_snaps/utils-yaml.md           | 14 +++++++---
 tests/testthat/test-build-favicons.R          |  5 ++--
 tests/testthat/test-utils-yaml.R              |  5 ++--
 20 files changed, 113 insertions(+), 69 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index c7138f547b..61e3f2742c 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -65,6 +65,7 @@ Config/Needs/website: usethis, servr
 Config/potools/style: explicit
 Config/testthat/edition: 3
 Config/testthat/parallel: true
+Config/testthat/start-first: build-articles, build-reference
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
diff --git a/R/build-favicons.R b/R/build-favicons.R
index ed137c6864..27c425d2a1 100644
--- a/R/build-favicons.R
+++ b/R/build-favicons.R
@@ -24,9 +24,10 @@ build_favicons <- function(pkg = ".", overwrite = FALSE) {
   logo_path <- find_logo(pkg$src_path)
 
   if (is.null(logo_path)) {
-    cli::cli_abort(
-      "Can't find package logo PNG or SVG to build favicons."
-    )
+    cli::cli_abort(c(
+      "Can't find package logo PNG or SVG to build favicons.",
+      "i" = "See {.fun usethis::use_logo} for more information."
+    ))
   }
 
   if (has_favicons(pkg) && !overwrite) {
@@ -37,7 +38,9 @@ build_favicons <- function(pkg = ".", overwrite = FALSE) {
     return(invisible())
   }
 
-  cli::cli_inform("Building favicons with {.url https://realfavicongenerator.net} ...")
+  cli::cli_inform(c(
+    i = "Building favicons with {.url https://realfavicongenerator.net} ..."
+  ))
 
   logo <- readBin(logo_path, what = "raw", n = fs::file_info(logo_path)$size)
 
diff --git a/R/build-home-index.R b/R/build-home-index.R
index 6a1bf620fb..c59503e45f 100644
--- a/R/build-home-index.R
+++ b/R/build-home-index.R
@@ -54,7 +54,7 @@ data_home <- function(pkg = ".") {
 }
 
 
-data_home_sidebar <- function(pkg = ".") {
+data_home_sidebar <- function(pkg = ".", call = caller_env()) {
 
   pkg <- as_pkgdown(pkg)
   if (isFALSE(pkg$meta$home$sidebar))
@@ -75,7 +75,7 @@ data_home_sidebar <- function(pkg = ".") {
           "Can't locate {.file {rel_html_path}}.",
           x = paste0(msg_fld, " is misconfigured.")
         ),
-        call = caller_env()
+        call = call
       )
 
 
@@ -114,7 +114,8 @@ data_home_sidebar <- function(pkg = ".") {
       components,
       names(components),
       data_home_component,
-      pkg = pkg
+      pkg = pkg,
+      call = call
       ) %>%
       set_names(names(components))
   )
@@ -122,7 +123,8 @@ data_home_sidebar <- function(pkg = ".") {
   check_yaml_has(
     setdiff(sidebar_structure, names(sidebar_components)),
     where = c("home", "sidebar", "components"),
-    pkg = pkg
+    pkg = pkg,
+    call = call
   )
 
   sidebar_final_components <- purrr::compact(
@@ -138,12 +140,13 @@ default_sidebar_structure <- function() {
   c("links", "license", "community", "citation", "authors", "dev")
 }
 
-data_home_component <- function(component, component_name, pkg) {
+data_home_component <- function(component, component_name, pkg, call = caller_env()) {
 
   check_yaml_has(
     setdiff(c("title", "text"), names(component)),
     where = c("home", "sidebar", "components", component_name),
-    pkg = pkg
+    pkg = pkg,
+    call = call
   )
 
   sidebar_section(
diff --git a/R/development.R b/R/development.R
index 7c07674145..4f02ed309e 100644
--- a/R/development.R
+++ b/R/development.R
@@ -58,9 +58,9 @@ dev_mode_auto <- function(version) {
 check_mode <- function(mode) {
   valid_mode <- c("auto", "default", "release", "devel", "unreleased")
   if (!mode %in% valid_mode) {
-    abort(paste0(
-      "`development.mode` in `_pkgdown.yml` must be one of ",
-      paste(valid_mode, collapse = ", ")
+    cli::cli_abort(c(
+      "{.field development.mode} must be one of {.or {valid_mode}}.",
+      i = "Use an approriate value in {.run [_pkgdown.yml](usethis::edit_pkgdown_config())}"
     ))
   }
 }
diff --git a/R/sitrep.R b/R/sitrep.R
index e67ca7d45a..7d2bfa217f 100644
--- a/R/sitrep.R
+++ b/R/sitrep.R
@@ -18,7 +18,7 @@ pkgdown_sitrep <- function(pkg = ".") {
 
   if (is.null(pkg$meta[["url"]])) {
     msg_fld <- pkgdown_field(pkg, "url", cfg = TRUE, fmt = TRUE)
-    warns <- c(warns, x = paste0(msg_fld, "is misconfigured. See {.vignette pkgdown::metatdata}."))
+    warns <- c(warns, x = paste0(msg_fld, " is misconfigured. See {.vignette pkgdown::metatdata}."))
   }
 
   desc_urls <- pkg$desc$get_urls()
@@ -28,10 +28,12 @@ pkgdown_sitrep <- function(pkg = ".") {
   }
 
   if (length(warns) == 0) {
-    cli::cli_alert_success("pkgdown situation report: {.emph {cli::col_green('all clear')}}")
-    cli::cli_inform("{.emph Double-check the following URLs:}")
-    cli::cli_inform("{.file {pkgdown_config_relpath(pkg)}} contains URL {.url {pkg$meta['url']}}")
-    cli::cli_inform("{.file DESCRIPTION} contains URL{?s} {.url {desc_urls}}")
+    cli::cli_inform(c(
+      "v" = "pkgdown situation report: {.emph {cli::col_green('all clear')}}",
+       "!" = "{.emph Double-check the following URLs:}",
+       " " = "{pkgdown_config_href({pkg$src_path})} contains URL {.url {pkg$meta['url']}}",
+       " " = "{.file DESCRIPTION} contains URL{?s} {.url {desc_urls}}"
+    ))
   } else {
     cli::cli_warn(c(
       "pkgdown situation report: {.emph {cli::col_red('configuration error')}}",
diff --git a/R/theme.R b/R/theme.R
index eb7e3f142c..4d0c780c4f 100644
--- a/R/theme.R
+++ b/R/theme.R
@@ -112,7 +112,7 @@ check_bootswatch_theme <- function(bootswatch_theme, bs_version, pkg) {
         bs_version,
         pkgdown_field(pkg, c("template", "bootstrap"))
       ),
-      x = "Edit settings in {.file {pkgdown_config_relpath(pkg)}}"
+      x = "Edit settings in {pkgdown_config_href({pkg$src_path})}"
     ), call = caller_env())
   }
 
diff --git a/R/topics.R b/R/topics.R
index 9bf17c9fa3..6ff7a67819 100644
--- a/R/topics.R
+++ b/R/topics.R
@@ -10,8 +10,10 @@ select_topics <- function(match_strings, topics, check = FALSE) {
   # If none of the specified topics have a match, return no topics
   if (purrr::every(indexes, is_empty)) {
     if (check) {
-      cli::cli_abort(
-        "No topics matched in {.file _pkgdown.yml}. No topics selected.",
+      cli::cli_abort(c(
+        "No topics matched in pkgdown config. No topics selected.",
+        i = "Run {.run usethis::edit_pkgdown_config()} to edit."
+        ),
         call = caller_env()
       )
     }
@@ -177,8 +179,10 @@ match_eval <- function(string, env) {
 }
 
 topic_must <- function(message, topic, ..., call = NULL) {
-  cli::cli_abort(
-    "In {.file _pkgdown.yml}, topic must {message}, not {.val {topic}}.",
+  cli::cli_abort(c(
+    "Topic must {message}, not {.val {topic}}.",
+    i = "Run {.run usethis::edit_pkgdown_config()} to edit."
+    ),
     ...,
     call = call
   )
diff --git a/R/utils-yaml.R b/R/utils-yaml.R
index ff8ece88d6..127d3b6fb6 100644
--- a/R/utils-yaml.R
+++ b/R/utils-yaml.R
@@ -1,14 +1,16 @@
-check_yaml_has <- function(missing, where, pkg) {
+check_yaml_has <- function(missing, where, pkg, call = caller_env()) {
   if (length(missing) == 0) {
     return()
   }
 
   missing_components <- lapply(missing, function(x) c(where, x))
-  msg_flds <- pkgdown_field(pkg, missing_components, fmt = TRUE, cfg = TRUE)
+  msg_flds <- pkgdown_field(pkg, missing_components, fmt = FALSE, cfg = FALSE)
 
-  cli::cli_abort(
-    paste0("Can't find {cli::qty(missing)} component{?s} ", msg_flds, "."),
-    call = caller_env()
+  cli::cli_abort(c(
+    "Can't find {cli::qty(missing)} component{?s} {.field {msg_flds}}.",
+    i = "Edit {pkgdown_config_href({pkg$src_path})} to define {cli::qty(missing)} {?it/them}."
+    ),
+    call = call
   )
 }
 
@@ -38,9 +40,10 @@ pkgdown_field <- function(pkg, fields, cfg = FALSE, fmt = FALSE) {
   }
 
   if (cfg) {
-    config_path <- pkgdown_config_relpath(pkg)
     if (fmt) {
-      config_path <- paste0("{.file ", config_path, "}")
+      config_path <- cli::format_inline(pkgdown_config_href(pkg$src_path))
+    } else {
+      config_path <- pkgdown_config_relpath(pkg)
     }
 
     paste0(flds, " in ", config_path)
diff --git a/tests/testthat/_snaps/build-favicons.md b/tests/testthat/_snaps/build-favicons.md
index 21f970cf14..622da598bf 100644
--- a/tests/testthat/_snaps/build-favicons.md
+++ b/tests/testthat/_snaps/build-favicons.md
@@ -1,3 +1,12 @@
+# missing logo generates message
+
+    Code
+      expect_output(build_favicons(pkg), "Building favicons")
+    Condition
+      Error in `build_favicons()`:
+      ! Can't find package logo PNG or SVG to build favicons.
+      i See `usethis::use_logo()` for more information.
+
 # existing logo generates message
 
     Code
diff --git a/tests/testthat/_snaps/build-home-index.md b/tests/testthat/_snaps/build-home-index.md
index afad1e7cb3..c8dc8c4f7e 100644
--- a/tests/testthat/_snaps/build-home-index.md
+++ b/tests/testthat/_snaps/build-home-index.md
@@ -49,7 +49,7 @@
 # data_home_sidebar() errors well when no HTML file
 
     Can't locate 'file.html'.
-    x home.sidebar.html in '_pkgdown.yml' is misconfigured.
+    x home.sidebar.html in _pkgdown.yml is misconfigured.
 
 # data_home_sidebar() can get a custom markdown formatted component
 
@@ -74,17 +74,18 @@
     Code
       data_home_sidebar(pkg)
     Condition
-      Error in `data_home_sidebar()`:
-      ! Can't find component home.sidebar.components.fancy in '_pkgdown.yml'.
+      Error:
+      ! Can't find component home.sidebar.components.fancy.
+      i Edit _pkgdown.yml to define it.
 
 ---
 
     Code
       data_home_sidebar(pkg)
     Condition
-      Error in `data_home_sidebar()`:
-      ! Can't find components home.sidebar.components.fancy in '_pkgdown.yml'.
-      Can't find components home.sidebar.components.cool in '_pkgdown.yml'.
+      Error:
+      ! Can't find components home.sidebar.components.fancy and home.sidebar.components.cool.
+      i Edit _pkgdown.yml to define them.
 
 ---
 
@@ -94,8 +95,9 @@
       Error in `purrr::map2()`:
       i In index: 1.
       i With name: fancy.
-      Caused by error in `.f()`:
-      ! Can't find component home.sidebar.components.fancy.title in '_pkgdown.yml'.
+      Caused by error:
+      ! Can't find component home.sidebar.components.fancy.title.
+      i Edit _pkgdown.yml to define it.
 
 ---
 
@@ -105,7 +107,7 @@
       Error in `purrr::map2()`:
       i In index: 1.
       i With name: fancy.
-      Caused by error in `.f()`:
-      ! Can't find components home.sidebar.components.fancy.title in '_pkgdown.yml'.
-      Can't find components home.sidebar.components.fancy.text in '_pkgdown.yml'.
+      Caused by error:
+      ! Can't find components home.sidebar.components.fancy.title and home.sidebar.components.fancy.text.
+      i Edit _pkgdown.yml to define them.
 
diff --git a/tests/testthat/_snaps/build-redirects.md b/tests/testthat/_snaps/build-redirects.md
index 5d392178e4..be5850182c 100644
--- a/tests/testthat/_snaps/build-redirects.md
+++ b/tests/testthat/_snaps/build-redirects.md
@@ -5,5 +5,5 @@
     Condition
       Error:
       ! Entry 5 must be a character vector of length 2.
-      x Edit url in '_pkgdown.yml'.
+      x Edit url in _pkgdown.yml.
 
diff --git a/tests/testthat/_snaps/build-reference-index.md b/tests/testthat/_snaps/build-reference-index.md
index 726ce3988c..23bf49ce81 100644
--- a/tests/testthat/_snaps/build-reference-index.md
+++ b/tests/testthat/_snaps/build-reference-index.md
@@ -60,7 +60,7 @@
     i In index: 1.
     Caused by error in `.f()`:
     ! Item 2 in section 1 is empty.
-    x Delete the empty line or add function name to reference in '_pkgdown.yml'.
+    x Delete the empty line or add function name to reference in _pkgdown.yml.
 
 # errors well when a content entry is not a character
 
@@ -71,7 +71,7 @@
       i In index: 1.
       Caused by error in `.f()`:
       ! Item 2 in section 1 must be a character.
-      x You might need to add '' around e.g. - 'N' or - 'off' to reference in '_pkgdown.yml'.
+      x You might need to add '' around e.g. - 'N' or - 'off' to reference in _pkgdown.yml.
 
 # errors well when a content entry refers to a not installed package
 
diff --git a/tests/testthat/_snaps/development.md b/tests/testthat/_snaps/development.md
index bfa6c2ce68..31805659ee 100644
--- a/tests/testthat/_snaps/development.md
+++ b/tests/testthat/_snaps/development.md
@@ -4,5 +4,6 @@
       check_mode("foo")
     Condition
       Error in `check_mode()`:
-      ! `development.mode` in `_pkgdown.yml` must be one of auto, default, release, devel, unreleased
+      ! development.mode must be one of auto, default, release, devel, or unreleased.
+      i Use an approriate value in `_pkgdown.yml`
 
diff --git a/tests/testthat/_snaps/package.md b/tests/testthat/_snaps/package.md
index f556c9cf4f..959f03b8da 100644
--- a/tests/testthat/_snaps/package.md
+++ b/tests/testthat/_snaps/package.md
@@ -5,5 +5,5 @@
     Condition
       Error:
       ! Boostrap version must be 3 or 5.
-      x You set a value of 1 to template.bootstrap in '_pkgdown.yml'.
+      x You set a value of 1 to template.bootstrap in _pkgdown.yml.
 
diff --git a/tests/testthat/_snaps/render.md b/tests/testthat/_snaps/render.md
index 7008238739..d9ddfc5f39 100644
--- a/tests/testthat/_snaps/render.md
+++ b/tests/testthat/_snaps/render.md
@@ -1,7 +1,7 @@
 # check_bootswatch_theme() works
 
     Can't find Bootswatch theme "paper" (template.bootswatch) for Bootstrap version "4" (template.bootstrap).
-    x Edit settings in '_pkgdown.yml'
+    x Edit settings in _pkgdown.yml
 
 # capture data_template()
 
diff --git a/tests/testthat/_snaps/sitrep.md b/tests/testthat/_snaps/sitrep.md
index 46c8636652..9db0b11982 100644
--- a/tests/testthat/_snaps/sitrep.md
+++ b/tests/testthat/_snaps/sitrep.md
@@ -5,7 +5,7 @@
     Condition
       Warning:
       pkgdown situation report: configuration error
-      x url in '_pkgdown.yml'is misconfigured. See `vignette(pkgdown::metatdata)`.
+      x url in _pkgdown.yml is misconfigured. See `vignette(pkgdown::metatdata)`.
       x 'DESCRIPTION' URL is empty.
 
 ---
@@ -22,7 +22,8 @@
     Code
       pkgdown_sitrep(pkg)
     Message
-      Double-check the following URLs:
-      '_pkgdown.yml' contains URL <http://example.com/pkg>
-      'DESCRIPTION' contains URL <http://example.com/pkg>
+      v pkgdown situation report: all clear
+      ! Double-check the following URLs:
+        _pkgdown.yml contains URL <http://example.com/pkg>
+        'DESCRIPTION' contains URL <http://example.com/pkg>
 
diff --git a/tests/testthat/_snaps/topics.md b/tests/testthat/_snaps/topics.md
index 7d3e10dbe7..a595eec157 100644
--- a/tests/testthat/_snaps/topics.md
+++ b/tests/testthat/_snaps/topics.md
@@ -6,21 +6,24 @@
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be valid R code, not "x + ".
+      ! Topic must be valid R code, not "x + ".
+      i Run `usethis::edit_pkgdown_config()` to edit.
     Code
       t <- select_topics("y", topics)
     Condition
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be a known topic name or alias, not "y".
+      ! Topic must be a known topic name or alias, not "y".
+      i Run `usethis::edit_pkgdown_config()` to edit.
     Code
       t <- select_topics("paste(1)", topics)
     Condition
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be a known selector function, not "paste(1)".
+      ! Topic must be a known selector function, not "paste(1)".
+      i Run `usethis::edit_pkgdown_config()` to edit.
       Caused by error in `paste()`:
       ! could not find function "paste"
     Code
@@ -29,19 +32,22 @@
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be a known topic name or alias, not "starts_with".
+      ! Topic must be a known topic name or alias, not "starts_with".
+      i Run `usethis::edit_pkgdown_config()` to edit.
     Code
       t <- select_topics("1", topics)
     Condition
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be a string or function call, not "1".
+      ! Topic must be a string or function call, not "1".
+      i Run `usethis::edit_pkgdown_config()` to edit.
     Code
       t <- select_topics("starts_with('y')", topics, check = TRUE)
     Condition
       Error:
-      ! No topics matched in '_pkgdown.yml'. No topics selected.
+      ! No topics matched in pkgdown config. No topics selected.
+      i Run `usethis::edit_pkgdown_config()` to edit.
 
 # can select by name or alias
 
@@ -51,14 +57,16 @@
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be a known topic name or alias, not "a4".
+      ! Topic must be a known topic name or alias, not "a4".
+      i Run `usethis::edit_pkgdown_config()` to edit.
     Code
       select_topics("c::a", topics)
     Condition
       Error in `purrr::map()`:
       i In index: 1.
       Caused by error:
-      ! In '_pkgdown.yml', topic must be a known topic name or alias, not "c::a".
+      ! Topic must be a known topic name or alias, not "c::a".
+      i Run `usethis::edit_pkgdown_config()` to edit.
 
 # an unmatched selection generates a warning
 
@@ -66,5 +74,6 @@
       select_topics(c("a", "starts_with('unmatched')"), topics, check = TRUE)
     Condition
       Error:
-      ! In '_pkgdown.yml', topic must match a function or concept, not "starts_with('unmatched')".
+      ! Topic must match a function or concept, not "starts_with('unmatched')".
+      i Run `usethis::edit_pkgdown_config()` to edit.
 
diff --git a/tests/testthat/_snaps/utils-yaml.md b/tests/testthat/_snaps/utils-yaml.md
index 2f000754a0..c98b9e03c2 100644
--- a/tests/testthat/_snaps/utils-yaml.md
+++ b/tests/testthat/_snaps/utils-yaml.md
@@ -1,14 +1,22 @@
 # pkgdown_field produces useful description
 
+    Code
+      cli::cli_inform(pkgdown_field(pkg, c("a"), cfg = TRUE, fmt = TRUE))
+    Message
+      a in _pkgdown.yml
+
+---
+
     Code
       check_yaml_has("x", where = "a", pkg = pkg)
     Condition
       Error:
-      ! Can't find component a.x in '_pkgdown.yml'.
+      ! Can't find component a.x.
+      i Edit _pkgdown.yml to define it.
     Code
       check_yaml_has(c("x", "y"), where = "a", pkg = pkg)
     Condition
       Error:
-      ! Can't find components a.x in '_pkgdown.yml'.
-      Can't find components a.y in '_pkgdown.yml'.
+      ! Can't find components a.x and a.y.
+      i Edit _pkgdown.yml to define them.
 
diff --git a/tests/testthat/test-build-favicons.R b/tests/testthat/test-build-favicons.R
index dbc1cea905..aaeb3a9791 100644
--- a/tests/testthat/test-build-favicons.R
+++ b/tests/testthat/test-build-favicons.R
@@ -1,9 +1,8 @@
 test_that("missing logo generates message", {
   pkg <- local_pkgdown_site(test_path("assets/site-empty"))
 
-  expect_error(
-    expect_snapshot(build_favicons(pkg)),
-    "Can't find package logo"
+  expect_snapshot(error = TRUE,
+    expect_output(build_favicons(pkg), "Building favicons")
   )
 })
 
diff --git a/tests/testthat/test-utils-yaml.R b/tests/testthat/test-utils-yaml.R
index 20477723ff..c18d1dd390 100644
--- a/tests/testthat/test-utils-yaml.R
+++ b/tests/testthat/test-utils-yaml.R
@@ -7,9 +7,8 @@ test_that("pkgdown_field produces useful description", {
   expect_equal(pkgdown_field(pkg, c("a", "b")), "a.b")
   expect_equal(pkgdown_field(pkg, c("a", "b"), fmt = TRUE), "{.field a.b}")
   expect_equal(pkgdown_field(pkg, c("a"), cfg = TRUE), "a in _pkgdown.yml")
-  expect_equal(
-    pkgdown_field(pkg, c("a"), cfg = TRUE, fmt = TRUE),
-    "{.field a} in {.file _pkgdown.yml}"
+  expect_snapshot(
+    cli::cli_inform(pkgdown_field(pkg, c("a"), cfg = TRUE, fmt = TRUE))
   )
 
   expect_snapshot(error = TRUE, {