Allow overriding default knitr chunk options

NEWS.md

@@ -1,5 +1,10 @@
 # roxygen2 (development version)
 
+* The new `knitr_chunk_options` option (in the `Roxygen` entry of
+  `DESCRIPTION` or in `man/roxygen/meta.R`) is added to the knitr chunk
+  options that roxygen2 uses for markdown code blocks and inline
+  code (#1390).
+
 * `@includeRmd` now gives better feedback when it fails (#1089).
 
 * `@export` will now export both the class and constructor function when

R/markdown.R

@@ -154,7 +154,13 @@ eval_code_node <- function(node, env) {
     # write knitr markup for fenced code
     text <- paste0("```", if (!is.na(lang)) lang, "\n", xml_text(node), "```\n")
   }
-  roxy_knit(text, env, knitr_chunk_defaults)
+
+  chunk_opts <- utils::modifyList(
+    knitr_chunk_defaults,
+    as.list(roxy_meta_get("knitr_chunk_options", NULL))
+  )
+
+  roxy_knit(text, env, chunk_opts)
 }
 
 knitr_chunk_defaults <- list(

R/options.R

@@ -28,6 +28,8 @@
 #' * `rd_family_title` `<list>`: overrides for `@family` titles. See the
 #'    _rd_ vignette for details: `vignette("rd", package = "roxygen2")`
 #'
+#' * `knitr_chunk_options`: default chunk options used for knitr.
+#'
 #' @section How to set:
 #' Either set in `DESCRIPTION`:
 #'
@@ -60,7 +62,8 @@ load_options <- function(base_path = ".") {
     markdown = FALSE,
     r6 = TRUE,
     current_package = NA_character_,
-    rd_family_title = list()
+    rd_family_title = list(),
+    knitr_chunk_options = NULL
   )
 
   unknown_opts <- setdiff(names(opts), names(defaults))
@@ -136,3 +139,10 @@ roxy_meta_load <- function(base_path = getwd()) {
   env_bind(roxy_meta, !!!load_options(base_path))
 }
 
+local_roxy_meta_set <- function(key, value, envir = caller_env()) {
+  old_value <- roxy_meta_get(key)
+  withr::defer(roxy_meta_set(key, old_value), envir = envir)
+
+  roxy_meta_set(key, value)
+}
+

tests/testthat/test-markdown.R

@@ -633,3 +633,18 @@ test_that("alternative knitr engines", {
     "))
   )
 })
+
+test_that("can override default options", {
+  local_roxy_meta_set("knitr_chunk_options", list(comment = "###"))
+
+  out <- roc_proc_text(rd_roclet(), "
+    #' Title
+    #'
+    #' ```{r}
+    #' 1+1
+    #' ```
+    #' @md
+    foo <- function() { }
+  ")[[1]]
+  expect_match(out$get_section("description")$value, "###", fixed = TRUE)
+})

vignettes/rd-formatting.Rmd

@@ -317,6 +317,9 @@ Code blocks support some knitr chunk options, e.g. to keep the output of several
 Some knitr chunk options are reset at the start of every code block, so if you want to change these, you'll have to specify them for every chunk.
 These are currently `r paste0("\x60", names(roxygen2:::knitr_chunk_defaults), "\x60")`.
 
+Alternatively, you can set the `knitr_chunk_options` option to override these defaults, or add new chunk options that are used for the whole package.
+See `?load_options` for specifying roxygen2 options.
+
 ### Images
 
 Plots will create `.png` files in the `man/figures` directory with file names coming from the chunk name.