Better feedback for @includeRmd (#1397)

Fixes #1089

NEWS.md

@@ -1,5 +1,7 @@
 # roxygen2 (development version)
 
+* `@includeRmd` now gives better feedback when it fails (#1089).
+
 * `@export` will now export both the class and constructor function when
   applied to expressions like `foo <- setClass("foo")` (#1216).
 

R/rd-include-rmd.R

@@ -12,6 +12,12 @@ roxy_tag_parse.roxy_tag_includeRmd <- function(x) {
 roxy_tag_rd.roxy_tag_includeRmd <- function(x, base_path, env) {
   rmd <- x$val$path
   section <- x$val$section
+
+  if (!file.exists(rmd)) {
+    warn_roxy_tag(x, "Can't find Rmd {.path {rmd}}")
+    return(NULL)
+  }
+
   if (section == "") section <- "details"
   stopifnot(is.character(rmd), length(rmd) == 1, !is.na(rmd))
 
@@ -43,18 +49,27 @@ roxy_tag_rd.roxy_tag_includeRmd <- function(x, base_path, env) {
   )
   cat(txt, file = rmd_path)
 
-  rmarkdown::render(
-    rmd_path,
-    output_format = "github_document",
-    output_options = c(
-      list(html_preview = FALSE),
-      if (utils::packageVersion("rmarkdown") >= "2.12") list(math_method = NULL)
+  tryCatch(
+    rmarkdown::render(
+      rmd_path,
+      output_format = "github_document",
+      output_options = c(
+        list(html_preview = FALSE),
+        if (utils::packageVersion("rmarkdown") >= "2.12") list(math_method = NULL)
+      ),
+      output_file = md_path,
+      quiet = TRUE,
+      envir = new_environment(parent = global_env())
     ),
-    output_file = md_path,
-    quiet = TRUE,
-    envir = new_environment(parent = global_env())
+    error = function(e) {
+      warn_roxy_tag(x, "failed to evaluate Rmd", parent = e)
+    }
   )
 
+  if (!file.exists(md_path)) {
+    return(NULL)
+  }
+
   value <- rmd_eval_rd(md_path, x)
   rd_section_markdown(section, value)
 }

tests/testthat/_snaps/rd-include-rmd.md

@@ -0,0 +1,10 @@
+# useful warnings
+
+    [<text>:3] @includeRmd Can't find Rmd 'path'
+
+---
+
+    [<text>:3] @includeRmd failed to evaluate Rmd
+    Caused by error:
+    ! Error
+

tests/testthat/test-rd-include-rmd.R

@@ -255,3 +255,27 @@ test_that("order of sections is correct", {
   out1 <- roc_proc_text(rd_roclet(), rox)[[1]]
   expect_match(format(out1), "Rmd.*After.*After2")
 })
+
+test_that("useful warnings", {
+  skip_if_not(rmarkdown::pandoc_available("2.17"))
+
+  text <- "
+    #' Title
+    #' @includeRmd path
+    #' @name foobar
+    NULL"
+  expect_snapshot_warning(roc_proc_text(rd_roclet(), text))
+
+  path <- withr::local_tempfile(fileext = ".Rmd", lines = c(
+    "```{r}",
+    "stop('Error')",
+    "```"
+  ))
+  text <- sprintf("
+    #' Title
+    #' @includeRmd %s
+    #' @name foobar
+    NULL", path
+  )
+  expect_snapshot_warning(roc_proc_text(rd_roclet(), text))
+})