Add advice to use usethis::edit_pkgdown_config() (r-lib#2419)

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

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)
 

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,15 +114,17 @@ data_home_sidebar <- function(pkg = ".") {
       components,
       names(components),
       data_home_component,
-      pkg = pkg
+      pkg = pkg,
+      call = call
       ) %>%
       set_names(names(components))
   )
 
   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(

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())}"
     ))
   }
 }

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')}}",

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())
   }
 

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
   )

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)

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

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.
 

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.
 

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
 

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`
 

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.
 

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()
 

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>