Handle unmatched reference topics (#730)

Two scenarios are addressed:

* If a topic selector does not match anything, a warning is generated.

* If a _pkgdown.yml file has selectors but *none* of them match, a warning is generated saying all topics will be selected.

Closes #728

NEWS.md

@@ -1,5 +1,8 @@
 # pkgdown 1.1.0.9000
 
+* `build_reference_index()`: Selectors that do not match topics now generate a warning.
+  If none of the specified selectors have a match, no topics are selected (#728).
+
 * Support of multiple arguments in `\Sexpr{}` was fixed, eliminating `x must be a
   string or a R connection` errors when using `\doi` Rd tags (#738).
 

R/build-reference-index.R

@@ -12,7 +12,7 @@ data_reference_index <- function(pkg = ".") {
 
   # Cross-reference complete list of topics vs. topics found in index page
   all_topics <- meta %>%
-    purrr::map(~ select_topics(.$contents, pkg$topics)) %>%
+    purrr::map(~ select_topics(.$contents, pkg$topics, check = TRUE)) %>%
     purrr::reduce(union)
   in_index <- seq_along(pkg$topics$name) %in% all_topics
 

R/topics.R

@@ -1,21 +1,36 @@
 # @return An integer vector giving selected topics
-select_topics <- function(match_strings, topics) {
+select_topics <- function(match_strings, topics, check = FALSE) {
   n <- nrow(topics)
   if (length(match_strings) == 0) {
     return(integer())
   }
 
   indexes <- purrr::map(match_strings, match_eval, env = match_env(topics))
 
+  # If none of the specified topics have a match, return no topics
+  if (check && length(purrr::keep(indexes, ~ length(.x) > 0)) == 0) {
+    warning(
+      "No topics matched in '_pkgdown.yml'. No topics selected.",
+      call. = FALSE,
+      immediate. = TRUE
+    )
+    return(integer())
+  }
+
   # Combine integer positions; adding if +ve, removing if -ve
   sel <- switch(
     all_sign(indexes[[1]], match_strings[[0]]),
     "+" = integer(),
     "-" = seq_len(n)[!topics$internal]
   )
+
   for (i in seq_along(indexes)) {
     index <- indexes[[i]]
 
+    if (check && length(index) == 0) {
+      topic_must("match a function or concept", expr = match_strings[[i]])
+    }
+
     sel <- switch(all_sign(index, match_strings[[i]]),
       "+" = union(sel, index),
       "-" = setdiff(sel, -index)

tests/testthat/test-topics.R

@@ -54,3 +54,21 @@ test_that("internal selected by name or with internal = TRUE", {
   expect_equal(select_topics("i", topics), 5)
   expect_equal(select_topics("starts_with('i', internal = TRUE)", topics), 5)
 })
+
+test_that("an unmatched selection generates a warning", {
+  expect_warning(
+    select_topics(c("a", "starts_with('unmatched')"), topics, check = TRUE),
+    "topic must match a function or concept"
+  )
+})
+
+test_that("no topics are returned if no topics are matched", {
+  expect_warning(
+    expect_equal(
+      select_topics("starts_with('unmatched')", topics, check = TRUE),
+      integer()
+    ),
+    "No topics selected"
+  )
+})
+