Merge branch 'main' into preview-url-verbose

Author: cderv

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: quarto
 Title: R Interface to 'Quarto' Markdown Publishing System
-Version: 1.4.4.9019
+Version: 1.4.4.9022
 Authors@R: c(
     person("JJ", "Allaire", , "[email protected]", role = "aut",
            comment = c(ORCID = "0000-0003-0174-9868")),

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(add_spin_preamble)
 export(check_newer_version)
 export(is_using_quarto)
 export(new_blog_post)

NEWS.md

@@ -2,6 +2,12 @@
 
 - `quarto_preview()` now explicitly returns the preview server URL (invisibly) and documents this behavior. This enables programmatic workflows such as taking screenshots with **webshot2** or passing the URL to other automation tools (thanks, @cwickham, #233).
 
+- Added `add_spin_preamble()` function to add YAML preambles to R scripts for use with Quarto Script rendering support. The function automatically detects existing preambles and provides flexible customization options through `title` and `preamble` parameters (#164).
+
+- `quarto_create_project()` gains a `title` argument to set the project title independently from the directory name. This allows creating projects with custom titles, including when using `name = "."` to create a project in the current directory (thanks, @davidkane9, #148). This matches with `--title` addition for `quarto create project` in Quarto CLI v1.5.15.
+
+- `quarto_use_template()` now supports using templates in another empty directory via the `dir` argument. However, the function will fail with a clear error message when used in non-empty directories, as interactive prompting is required and handled by Quarto CLI directly (requires Quarto 1.5.15+). Follow for [quarto-dev/quarto-cli#11127](https://github.com/quarto-dev/quarto-cli/issues/11127) for change with `--no-prompt` behavior in future Quarto versions.
+
 - `quarto_render(output_file = )` now sets the `output-file` Quarto metadata instead of the `--output` CLI flag. This allows the output file information to correctly be processed by Quarto, as if passed in a YAML header. e.g. it allows to support multiple output formats in the same render call. `quarto_render(quarto_args = c('--output', 'dummy.html'))` can still be used to set the `--output` CLI flag to enforce using the CLI flag and not the metadata processed by Quarto (#251, #43).
 
 - Added `check_newer_version()` function to check if a newer version of Quarto is available. The function compares the current Quarto version against the latest stable and prerelease versions. It is aimed for verbosity by default (`verbose = TRUE`), but `verbose = FALSE` can also be set for just checking update availability with TRUE or FALSE return values. Version information is cached per session for up to 24 hours to minimize network requests.

R/blog.R

@@ -89,8 +89,7 @@ make_post_yaml <- function(title, ...) {
   if (length(yml_values$categories) == 0) {
     yml_values <- yml_values[names(yml_values) != "categories"]
   }
-  yml_values <- as_yaml(yml_values)
-  yml_values <- paste0("---\n", yml_values, "---\n")
+  yml_values <- as_yaml_block(yml_values)
   yml_values
 }
 

R/create.R

@@ -11,7 +11,11 @@
 #'
 #' @param type The type of project to create. As of Quarto 1.4, it can be one of
 #'   `r paste0("\\code{", paste(quarto_project_type, collapse = "}, \\code{"),"}")`.
-#' @param name The name of the project and the directory that will be created.
+#' @param name The name of the project and the directory that will be created. Special case
+#' is to use `name = "."` to create the project in the current directory. In that case provide `title`
+#' to set the project title.
+#' @param title The title of the project. By default, it will be the name of the project, same as directory name created.
+#' or "My project" if `name = "."`. If you want to set a different title, provide it here.
 #' @param dir The directory in which to create the new Quarto project, i.e. the
 #'   parent directory.
 #'
@@ -23,7 +27,17 @@
 #'
 #' @examples
 #' \dontrun{
+#' # Create a new project directory in another directory
 #' quarto_create_project("my-first-quarto-project", dir = "~/tmp")
+#'
+#' # Create a new project directory in the current directory
+#' quarto_create_project("my-first-quarto-project")
+#'
+#' # Create a new project with a different title
+#' quarto_create_project("my-first-quarto-project", title = "My Quarto Project")
+#'
+#' # Create a new project inside the current directory directly
+#' quarto_create_project(".", title = "My Quarto Project")
 #' }
 #'
 #'
@@ -32,23 +46,41 @@ quarto_create_project <- function(
   name,
   type = "default",
   dir = ".",
+  title = name,
   no_prompt = FALSE,
   quiet = FALSE,
   quarto_args = NULL
 ) {
   check_quarto_version(
     "1.4",
-    "quarto create project",
+    "quarto create project <type> <name>",
     "https://quarto.org/docs/projects/quarto-projects.html"
   )
 
   if (rlang::is_missing(name)) {
     cli::cli_abort("You need to provide {.arg name} for the new project.")
   }
 
+  # If title is provided, check for Quarto version 1.5.15 or higher
+  if (title != name) {
+    check_quarto_version(
+      "1.5.15",
+      "quarto create project <type> <name> <title>",
+      "https://quarto.org/docs/projects/quarto-projects.html"
+    )
+  }
+
   if (rlang::is_interactive() && !no_prompt) {
+    folder_msg <- if (name != ".") {
+      "as a folder named {.strong {name}}"
+    }
     cli::cli_inform(c(
-      "This will create a new Quarto {.emph {type}} project as a folder named {.strong {name}} in {.path {xfun::normalize_path(dir)}}."
+      paste(
+        "This will create a new Quarto {.emph {type}} project",
+        folder_msg,
+        "in {.path {xfun::normalize_path(dir)}}."
+      ),
+      "Project title will be set to {.strong {title}}."
     ))
     prompt_value <- tolower(readline(sprintf("Do you want to proceed (Y/n)? ")))
     if (!prompt_value %in% c("", "y")) {
@@ -62,7 +94,7 @@ quarto_create_project <- function(
     "project",
     type,
     name,
-    name,
+    title,
     "--no-prompt",
     "--no-open",
     if (is_quiet(quiet)) cli_arg_quiet(),

R/metadata.R

@@ -89,7 +89,6 @@ write_yaml_metadata_block <- function(..., .list = NULL) {
   if (length(meta) == 0) {
     return()
   }
-  res <- as_yaml(meta)
-  yaml_block <- paste0("---\n", res, "---\n")
+  yaml_block <- as_yaml_block(meta)
   knitr::asis_output(yaml_block)
 }

R/spin.R

@@ -0,0 +1,106 @@
+#' Add spin preamble to R script
+#'
+#' Adds a minimal spin preamble to an R script file if one doesn't already exist.
+#' The preamble includes a title derived from the filename and is formatted as
+#' a YAML block suitable preprended with `#'` for [knitr::spin()].
+#'
+#' This is useful to prepare R scripts for use with
+#' Quarto Script rendering support.
+#' See <https://quarto.org/docs/computations/render-scripts.html#knitr>
+#'
+#' @section Preamble format:
+#' For a script named `analysis.R`, the function adds this preamble by default:
+#' ```
+#' #' ---
+#' #' title: analysis
+#' #' ---
+#' #'
+#'
+#' # Original script content starts here
+#' ```
+#'
+#' This is the minimal preamble required for Quarto Script rendering, so that
+#' [Engine Bindings](https://quarto.org/docs/computations/execution-options.html#engine-binding) works.
+#'
+#' @param script Path to the R script file
+#' @param title Custom title for the preamble. If provided, overrides any title
+#'   in the `preamble` list. If NULL, uses `preamble$title` or filename as fallback.
+#' @param preamble Named list of YAML metadata to include in preamble.
+#'   The `title` parameter takes precedence over `preamble$title` if both are provided.
+#' @return Invisibly returns the script path if modified, otherwise invisible NULL
+#'
+#' @examples
+#' \dontrun{
+#' # Basic usage with default title
+#' add_spin_preamble("analysis.R")
+#'
+#' # Custom title
+#' add_spin_preamble("analysis.R", title = "My Analysis")
+#'
+#' # Custom preamble with multiple fields
+#' add_spin_preamble("analysis.R", preamble = list(
+#'   title = "Advanced Analysis",
+#'   author = "John Doe",
+#'   date = Sys.Date(),
+#'   format = "html"
+#' ))
+#'
+#' # Title parameter overrides preamble title
+#' add_spin_preamble("analysis.R",
+#'   title = "Final Title",  # This takes precedence
+#'   preamble = list(
+#'     title = "Ignored Title",
+#'     author = "John Doe"
+#'   )
+#' )
+#' }
+#' @export
+add_spin_preamble <- function(script, title = NULL, preamble = NULL) {
+  if (!fs::file_exists(script)) {
+    cli::cli_abort(c(
+      "File {.file {script}} does not exist.",
+      "Please provide a valid file path."
+    ))
+  }
+
+  content <- xfun::read_utf8(script)
+
+  # if files starts with a spin preamble, do nothing
+  if (grepl("^\\s*#'", content[1])) {
+    cli::cli_inform(c(
+      "File {.file {script}} already has a spin preamble.",
+      "No changes made. Edit manually if needed."
+    ))
+    return(invisible())
+  }
+
+  # Build preamble metadata
+  metadata <- list()
+
+  # Start with preamble list if provided
+  if (!is.null(preamble)) {
+    if (!is.list(preamble)) {
+      cli::cli_abort("`preamble` must be a named list.")
+    }
+    metadata <- preamble
+  }
+
+  # Add or override title
+  if (!is.null(title)) {
+    metadata$title <- title
+  } else if (is.null(metadata$title)) {
+    # Use filename as default title if none provided
+    metadata$title <- fs::path_file(fs::path_ext_remove(script))
+  }
+
+  preamble_text <- paste(
+    "#'",
+    xfun::split_lines(as_yaml_block(metadata))
+  )
+
+  new_content <- c(preamble_text, "", content)
+  xfun::write_utf8(new_content, con = script)
+
+  cli::cli_inform("Added spin preamble to {.file {script}}")
+  return(invisible(script))
+}

R/use.R

@@ -8,28 +8,42 @@
 #' @param template The template to install, either an archive or a GitHub
 #'   repository as described in the documentation
 #'   <https://quarto.org/docs/extensions/formats.html>.
-#'
+#' @param dir The directory in which to install the template. This must be an empty directory.
+#'   To use directly in a non-empty directory, use `quarto use template` interactively in the terminal for safe installation
+#'   without overwrite.
 #' @param quiet Suppress warnings and messages.
 #'
 #'
 #' @examples
 #' \dontrun{
-#' # Install a template and set up a draft document from a GitHub repository
+#' # Use a template and set up a draft document from a GitHub repository
 #' quarto_use_template("quarto-journals/jss")
 #'
-#' # Install a template and set up a draft document from a ZIP archive
+#' # Use a template in current directory by installing it in an empty directory
+#' quarto_use_template("quarto-journals/jss", dir = "new-empty-dir")
+#'
+#' # Use a template and set up a draft document from a ZIP archive
 #' quarto_use_template("https://github.com/quarto-journals/jss/archive/refs/heads/main.zip")
 #' }
 #'
 #' @export
 quarto_use_template <- function(
   template,
+  dir = ".",
   no_prompt = FALSE,
   quiet = FALSE,
   quarto_args = NULL
 ) {
   rlang::check_required(template)
 
+  if (!is_empty_dir(dir) && quarto_available("1.5.15")) {
+    cli::cli_abort(c(
+      "{.arg dir} must be an empty directory.",
+      "x" = "The directory {.path {dir}} is not empty.",
+      " " = "Please provide an empty directory or use {.code quarto use template {template} } interactively in terminal."
+    ))
+  }
+
   quarto_bin <- find_quarto()
 
   # This will ask for approval or stop installation
@@ -47,8 +61,10 @@ quarto_use_template <- function(
     if (quarto_version() > "1.5.4" && is_quiet(quiet)) {
       args <- cli_arg_quiet(args)
     }
-
-    quarto_use(args, quarto_bin = quarto_bin, echo = !quiet)
+    xfun::in_dir(
+      dir,
+      quarto_use(args, quarto_bin = quarto_bin, echo = !quiet)
+    )
   }
 
   invisible()

R/utils.R

@@ -24,6 +24,12 @@ write_yaml <- function(x, file) {
   yaml::write_yaml(x, file, handlers = yaml_handlers)
 }
 
+as_yaml_block <- function(x) {
+  # Convert to YAML and wrap in a block
+  yaml_content <- as_yaml(x)
+  paste0("---\n", yaml_content, "---\n")
+}
+
 
 # inline knitr:::merge_list()
 merge_list <- function(x, y) {
@@ -65,3 +71,11 @@ has_internet <- function(host = "https://www.google.com") {
     }
   )
 }
+
+is_empty_dir <- function(dir) {
+  if (!dir.exists(dir)) {
+    return(FALSE)
+  }
+  files <- list.files(dir, all.files = TRUE, no.. = TRUE)
+  length(files) == 0
+}

_pkgdown.yml

@@ -68,3 +68,4 @@ reference:
     These functions are used to help with Quarto documents and projects:
   contents:
   - write_yaml_metadata_block
+  - add_spin_preamble