diff --git a/NEWS.md b/NEWS.md index 28ae905b..f7c4e48f 100644 --- a/NEWS.md +++ b/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 diff --git a/R/markdown.R b/R/markdown.R index 97363b61..e0cea5d5 100644 --- a/R/markdown.R +++ b/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( diff --git a/R/options.R b/R/options.R index a3a2d1e4..fbb9f5ae 100644 --- a/R/options.R +++ b/R/options.R @@ -28,6 +28,8 @@ #' * `rd_family_title` ``: 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) +} + diff --git a/man/load_options.Rd b/man/load_options.Rd index d8e056a3..c1356ad3 100644 --- a/man/load_options.Rd +++ b/man/load_options.Rd @@ -33,6 +33,7 @@ Options in \code{man/roxygen/meta.R} override those present in \code{DESCRIPTION \item \code{current_package} \verb{} (read only): name of package being documented. \item \code{rd_family_title} \verb{}: overrides for \verb{@family} titles. See the \emph{rd} vignette for details: \code{vignette("rd", package = "roxygen2")} +\item \code{knitr_chunk_options}: default chunk options used for knitr. } } diff --git a/tests/testthat/test-markdown.R b/tests/testthat/test-markdown.R index 907abe8f..06e108df 100644 --- a/tests/testthat/test-markdown.R +++ b/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) +}) diff --git a/vignettes/rd-formatting.Rmd b/vignettes/rd-formatting.Rmd index 23bb10b2..92d14bf4 100644 --- a/vignettes/rd-formatting.Rmd +++ b/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.