From 10aa37aaca19b2a0f9078e33c478f268e7a49c80 Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Sun, 10 Jul 2022 20:28:42 -0500
Subject: [PATCH] Better feedback for `@includeRmd`

Fixes #1089
---
 NEWS.md                                 |  2 ++
 R/rd-include-rmd.R                      | 33 ++++++++++++++++++-------
 tests/testthat/_snaps/rd-include-rmd.md | 10 ++++++++
 tests/testthat/test-rd-include-rmd.R    | 24 ++++++++++++++++++
 4 files changed, 60 insertions(+), 9 deletions(-)
 create mode 100644 tests/testthat/_snaps/rd-include-rmd.md

diff --git a/NEWS.md b/NEWS.md
index df0bba41..28ae905b 100644
--- a/NEWS.md
+++ b/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).
 
diff --git a/R/rd-include-rmd.R b/R/rd-include-rmd.R
index cf04c713..d86675fa 100644
--- a/R/rd-include-rmd.R
+++ b/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)
 }
diff --git a/tests/testthat/_snaps/rd-include-rmd.md b/tests/testthat/_snaps/rd-include-rmd.md
new file mode 100644
index 00000000..7659174d
--- /dev/null
+++ b/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
+
diff --git a/tests/testthat/test-rd-include-rmd.R b/tests/testthat/test-rd-include-rmd.R
index 00bb9591..42932b5d 100644
--- a/tests/testthat/test-rd-include-rmd.R
+++ b/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))
+})