Support Quarto articles

NEWS.md

@@ -1,5 +1,7 @@
 # usethis (development version)
 
+* `use_vignette()` and `use_article()` gain `type` to allow creating Quarto vignettes and articles (@olivroy, #1997).
+
 * `use_git()` no longer asks if you want to restart RStudio when using Positron.
 
 * `use_test()` and `use_r()` now work when you are in `tests/testthat/_snaps/{foo}.md` (@olivroy, #1988).

R/vignette.R

@@ -13,40 +13,60 @@
 #' @param name Base for file name to use for new vignette. Should consist only
 #'   of numbers, letters, `_` and `-`. Lower case is recommended.
 #' @param title The title of the vignette.
+#' @param type One of `"quarto"` or `"rmarkdown"`
 #' @seealso The [vignettes chapter](https://r-pkgs.org/vignettes.html) of
-#'   [R Packages](https://r-pkgs.org).
+#'   [R Packages](https://r-pkgs.org) and the [Quarto vignettes](https://quarto-dev.github.io/quarto-r/articles/hello.html) reference.
 #' @export
 #' @examples
 #' \dontrun{
 #' use_vignette("how-to-do-stuff", "How to do stuff")
 #' }
-use_vignette <- function(name, title = name) {
+use_vignette <- function(name, title = name, type = c("rmarkdown", "quarto")) {
   check_is_package("use_vignette()")
   check_required(name)
   check_vignette_name(name)
+  type <- arg_match(type)
 
   use_dependency("knitr", "Suggests")
-  use_dependency("rmarkdown", "Suggests")
 
-  proj_desc_field_update("VignetteBuilder", "knitr", overwrite = TRUE)
+  if (type == "rmarkdown") {
+    use_dependency("rmarkdown", "Suggests")
+    proj_desc_field_update("VignetteBuilder", "knitr", overwrite = FALSE)
+    use_vignette_template("vignette.Rmd", name, title)
+  } else if (type == "quarto") {
+    proj_desc_field_update("VignetteBuilder", "quarto", overwrite = FALSE)
+    use_vignette_template("vignette.qmd", name, title)
+    use_build_ignore("vignettes/*_files")
+    #use_git_ignore("*_files", "vignettes/")
+  }
   use_git_ignore("inst/doc")
 
-  use_vignette_template("vignette.Rmd", name, title)
 
   invisible()
 }
 
 #' @export
 #' @rdname use_vignette
-use_article <- function(name, title = name) {
+use_article <- function(name, title = name, type = c("rmarkdown", "quarto")) {
   check_is_package("use_article()")
 
+  type <- arg_match(type)
   deps <- proj_deps()
-  if (!"rmarkdown" %in% deps$package) {
-    proj_desc_field_update("Config/Needs/website", "rmarkdown", append = TRUE)
+
+  if (type == "rmarkdown") {
+    if (!"rmarkdown" %in% deps$package) {
+      proj_desc_field_update("Config/Needs/website", "rmarkdown", append = TRUE)
+    }
+
+    use_vignette_template("article.Rmd", name, title, subdir = "articles")
+  } else if (type == "quarto") {
+    if (!"quarto" %in% deps$package) {
+      proj_desc_field_update("Config/Needs/website", "quarto", append = TRUE)
+    }
+
+    use_vignette_template("article.qmd", name, title, subdir = "articles")
   }
 
-  use_vignette_template("article.Rmd", name, title, subdir = "articles")
   use_build_ignore("vignettes/articles")
 
   invisible()
@@ -62,12 +82,20 @@ use_vignette_template <- function(template, name, title, subdir = NULL) {
   if (!is.null(subdir)) {
     use_directory(path("vignettes", subdir))
   }
+
   use_git_ignore(c("*.html", "*.R"), directory = "vignettes")
+  # make sure nothing else is caught. (this should be assured as `.` are not allowed.)
+  vignette_ext <- path_ext(template)
+  arg_match0(vignette_ext, c("qmd", "Rmd"))
+  if (vignette_ext == "qmd") {
+    # https://quarto-dev.github.io/quarto-r/articles/hello.html
+    use_git_ignore("*_files", directory = "vignettes")
+  }
 
   if (is.null(subdir)) {
-    path <- path("vignettes", asciify(name), ext = "Rmd")
+    path <- path("vignettes", asciify(name), ext = vignette_ext)
   } else {
-    path <- path("vignettes", subdir, asciify(name), ext = "Rmd")
+    path <- path("vignettes", subdir, asciify(name), ext = vignette_ext)
   }
 
   data <- list(

inst/templates/article.qmd

@@ -0,0 +1,15 @@
+---
+title: "{{{ vignette_title }}}"
+format: html
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library({{Package}})
+```

inst/templates/vignette.qmd

@@ -0,0 +1,20 @@
+---
+title: "{{{ vignette_title }}}"
+format: html
+vignette: >
+  %\VignetteIndexEntry{Vignette's Title}
+  %\VignetteEngine{quarto::html}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library({{Package}})
+```
+

tests/testthat/test-vignette.R

@@ -25,13 +25,32 @@ test_that("use_vignette() does the promised setup", {
   expect_true("inst/doc" %in% ignores)
 
   deps <- proj_deps()
-  expect_true(
-    all(c("knitr", "rmarkdown") %in% deps$package[deps$type == "Suggests"])
+  expect_contains(
+    deps$package[deps$type == "Suggests"],
+    c("knitr", "rmarkdown")
   )
 
   expect_identical(proj_desc()$get_field("VignetteBuilder"), "knitr")
 })
 
+test_that("use_vignette() works with Quarto", {
+  create_local_package()
+
+  use_vignette("name", "title", type = "quarto")
+  expect_proj_file("vignettes/name.qmd")
+
+  ignores <- read_utf8(proj_path(".gitignore"))
+  expect_true("inst/doc" %in% ignores)
+
+  deps <- proj_deps()
+  expect_contains(
+    deps$package[deps$type == "Suggests"],
+    "knitr"
+  )
+
+  expect_identical(proj_desc()$get_field("VignetteBuilder"), "quarto")
+})
+
 # use_article -------------------------------------------------------------
 
 test_that("use_article goes in article subdirectory", {
@@ -54,6 +73,19 @@ test_that("use_article() adds rmarkdown to Config/Needs/website", {
   )
 })
 
+test_that("use_article() adds quarto to Config/Needs/website", {
+  create_local_package()
+  local_interactive(FALSE)
+
+  proj_desc_field_update("Config/Needs/website", "somepackage", append = TRUE)
+  use_article("name", "title", "quarto")
+
+  expect_setequal(
+    proj_desc()$get_list("Config/Needs/website"),
+    c("quarto", "somepackage")
+  )
+})
+
 # helpers -----------------------------------------------------------------
 
 test_that("valid_vignette_name() works", {