Add quarto_args to quarto_render()

cderv · cderv · commit 0884290b95db · 2024-01-25T11:51:40.000+01:00
closes #125
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: quarto
 Title: R Interface to 'Quarto' Markdown Publishing System
-Version: 1.3.6
+Version: 1.3.7
 Authors@R: c(
     person("JJ", "Allaire", , "jj@rstudio.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-0174-9868")),
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,7 @@
 # quarto (development version)
 
+- Add `quarto_args` to `quarto_render()` and other commands to pass additional arguments to `quarto` CLI commands. This is for advanced usage e.g. when new options are added to Quarto CLI that would not be user-facing in this package's functions (thanks, @gadenbuie, #125).
+
 - Add `quiet` argument to pass `--quiet` to `quarto` CLI commands
 
 - Error message now advises to re-run with `quiet = FALSE` because `quarto_render(quiet = TRUE)` will run `quarto render` in quiet mode (thanks to @gadenbuie, #126, @wlandau, #16).
diff --git a/R/add.R b/R/add.R
@@ -19,8 +19,6 @@
 #'
 #' @param no_prompt Do not prompt to confirm approval to download external extension.
 #'
-#' @param quarto_args Character vector of other `quarto` CLI flag pass to the command.
-#'
 #' @examples
 #' \dontrun{
 #' # Install a template and set up a draft document from a GitHub repository
diff --git a/R/inspect.R b/R/inspect.R
@@ -5,7 +5,7 @@
 #' and dependent resources.
 #'
 #' @inheritParams quarto_render
-#' @inheritParams quarto_add_extension
+#'
 #' @param input The input file or project directory to inspect.
 #'
 #' @return Named list. For input files, the list contains the elements
diff --git a/R/render.R b/R/render.R
@@ -41,6 +41,9 @@
 #' @param profile [Quarto project
 #'   profile(s)](https://quarto.org/docs/projects/profiles.html) to use. Either
 #'   a character vector of profile names or `NULL` to use the default profile.
+#' @param quarto_args Character vector of other `quarto` CLI flag pass to the
+#'   command. This is mainly for advanced usage, e.g it can be useful for new
+#'   options added to quarto CLI and not yet supported as function argument.
 #' @param pandoc_args Additional command line options to pass to pandoc.
 #' @param as_job Render as an RStudio background job. Default is "auto",
 #'   which will render individual documents normally and projects as
@@ -82,6 +85,7 @@ quarto_render <- function(input = NULL,
                           debug = FALSE,
                           quiet = FALSE,
                           profile = NULL,
+                          quarto_args = NULL,
                           pandoc_args = NULL,
                           as_job = getOption("quarto.render_as_job", "auto")) {
 
@@ -176,6 +180,9 @@ quarto_render <- function(input = NULL,
   if (!is.null(profile)) {
     args <- cli_arg_profile(profile, args)
   }
+  if (!is.null(quarto_args)) {
+    args <- c(args, quarto_args)
+  }
   if (!is.null(pandoc_args)) {
     args <- c(args, pandoc_args)
   }
diff --git a/R/use.R b/R/use.R
@@ -2,6 +2,7 @@
 #'
 #' Install and use a template for Quarto using `quarto use`.
 #'
+#' @inheritParams quarto_render
 #' @inheritParams quarto_add_extension
 #'
 #' @param template The template to install, either an archive or a GitHub
diff --git a/man/quarto_add_extension.Rd b/man/quarto_add_extension.Rd
diff --git a/man/quarto_inspect.Rd b/man/quarto_inspect.Rd
diff --git a/man/quarto_render.Rd b/man/quarto_render.Rd
diff --git a/man/quarto_use_template.Rd b/man/quarto_use_template.Rd
diff --git a/tests/testthat/_snaps/render.md b/tests/testthat/_snaps/render.md
@@ -0,0 +1,9 @@
+# quarto_args in quarto_render
+
+    Code
+      quarto_render("input.qmd", quiet = TRUE, quarto_args = c("--to", "native"))
+    Output
+      Running \
+        "<quarto full path>" \
+        render input.qmd --quiet --to native
+
diff --git a/tests/testthat/helper.R b/tests/testthat/helper.R
@@ -57,7 +57,15 @@ expect_snapshot_qmd_output <- function(name, input, output_file = NULL, ...) {
 }
 
 
-transform_quarto_cli_in_output <- function(lines) {
-  # it will be quarto.exe only on windows
-  gsub("quarto\\.(exe|cmd)", "quarto", lines)
+transform_quarto_cli_in_output <- function(full_path = FALSE) {
+  return(
+    function(lines) {
+      if (full_path) {
+        gsub(find_quarto(), "<quarto full path>", lines, fixed = TRUE)
+      } else {
+        # it will be quarto.exe only on windows
+        gsub("quarto\\.(exe|cmd)", "quarto", lines)
+      }
+    }
+  )
 }
diff --git a/tests/testthat/test-quarto.R b/tests/testthat/test-quarto.R
@@ -8,6 +8,6 @@ test_that("quarto_run gives guidance in error", {
   expect_snapshot(
     error = TRUE,
     quarto_run(c("rend", "--quiet")),
-    transform = transform_quarto_cli_in_output
+    transform = transform_quarto_cli_in_output()
     )
 })
diff --git a/tests/testthat/test-render.R b/tests/testthat/test-render.R
@@ -45,3 +45,16 @@ test_that("metadata-file and metadata are merged in quarto_render", {
     metadata_file = yaml, metadata = list(title = "test2")
   )
 })
+
+test_that("quarto_args in quarto_render", {
+  skip_if_no_quarto()
+  qmd <- local_qmd_file(c("content"))
+  withr::local_options(quarto.echo_cmd = TRUE)
+  withr::local_dir(dirname(qmd))
+  file.rename(basename(qmd), "input.qmd")
+  # metadata
+  expect_snapshot(
+    quarto_render("input.qmd", quiet = TRUE, quarto_args = c("--to", "native")),
+    transform = transform_quarto_cli_in_output(full_path = TRUE)
+  )
+})
