Soft deprecate build_rmd() (#2675)

Author: jennybc

NEWS.md

@@ -3,6 +3,7 @@
 * remotes has moved from Imports to Suggests (#2663).
 * `bash()`, `create()`, `missing_s3()`, `reload()`, `show_news()`, and `wd()` are now deprecated. These functions are all historical parts of our workflow that we no longer use or recommend. `create()` is superseded by `usethis::create_package()`.
 * `build_manual()` reports more details on failure (#2586).
+* `build_rmd()` is soft-deprecated and is discouraged for external use. It exists to be an internal helper for `build_readme()`.
 * `check_doc_fields()` is a new function that checks for missing `\value` and `\examples` fields in Rd files, which are commonly flagged by CRAN (#2525).
 * `build_vignettes()` and `clean_vignettes()` are now deprecated. We no longer recommend building vignettes in this way; instead use `pkgdown::build_article()` to render articles locally (#2488).
 * `build_site()` now just calls `pkgdown::build_site()`, meaning that you will get more (informative) output by default (#2578).

R/build-readme.R

@@ -1,22 +1,46 @@
-#' Build a Rmarkdown files package
+#' Build Rmarkdown files
 #'
-#' `build_rmd()` is a wrapper around [rmarkdown::render()] that first installs
-#' a temporary copy of the package, and then renders each `.Rmd` in a clean R
-#' session. `build_readme()` locates your `README.Rmd` and builds it into a
-#' `README.md`
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `build_rmd()` is deprecated, as it is a low-level helper for internal use. To
+#' render your package's `README.Rmd` or `README.qmd`, use [build_readme()]. To
+#' preview a vignette or article, use functions like [pkgdown::build_site()] or
+#' [pkgdown::build_article()].
 #'
 #' @param files The Rmarkdown files to be rendered.
 #' @param path path to the package to build the readme.
 #' @param ...  additional arguments passed to [rmarkdown::render()]
 #' @inheritParams install
 #' @inheritParams rmarkdown::render
 #' @export
+#' @keywords internal
 build_rmd <- function(
   files,
   path = ".",
   output_options = list(),
   ...,
   quiet = TRUE
+) {
+  lifecycle::deprecate_soft("2.5.0", "build_rmd()", "build_readme()")
+  build_rmd_impl(
+    files = files,
+    path = path,
+    output_options = output_options,
+    ...,
+    quiet = quiet
+  )
+}
+
+# Created as part of the deprecation process to de-export build_rmd().
+# We still want to use this internally without needing to suppress deprecation
+# signals.
+build_rmd_impl <- function(
+  files,
+  path = ".",
+  output_options = list(),
+  ...,
+  quiet = TRUE
 ) {
   check_dots_used(action = getOption("devtools.ellipsis_action", warn))
 
@@ -40,7 +64,9 @@ build_rmd <- function(
   output_options$html_preview <- FALSE
 
   for (path in paths) {
-    cli::cli_inform(c(i = "Building {.path {path}}"))
+    if (!quiet) {
+      cli::cli_inform(c(i = "Building {.path {path}}"))
+    }
     callr::r_safe(
       function(...) rmarkdown::render(...),
       args = list(
@@ -58,7 +84,17 @@ build_rmd <- function(
   invisible(TRUE)
 }
 
-#' @rdname build_rmd
+#' Build README
+#'
+#' Renders an executable README, such as `README.Rmd`, to `README.md`.
+#' Specifically, `build_readme()`:
+#' * Installs a copy of the package's current source to a temporary library
+#' * Renders the README in a clean R session
+#'
+#' @param path Path to the package to build the README.
+#' @param quiet If `TRUE`, suppresses most output. Set to `FALSE`
+#'   if you need to debug.
+#' @param ... Additional arguments passed to [rmarkdown::render()].
 #' @export
 build_readme <- function(path = ".", quiet = TRUE, ...) {
   pkg <- as.package(path)
@@ -81,5 +117,5 @@ build_readme <- function(path = ".", quiet = TRUE, ...) {
     )
   }
 
-  build_rmd(readme_path, path = path, quiet = quiet, ...)
+  build_rmd_impl(readme_path, path = path, quiet = quiet, ...)
 }

R/install.R

@@ -236,7 +236,11 @@ install_dev_deps <- function(
 local_install <- function(pkg = ".", quiet = TRUE, env = parent.frame()) {
   pkg <- as.package(pkg)
 
-  cli::cli_inform(c(i = "Installing {.pkg {pkg$package}} in temporary library"))
+  if (!quiet) {
+    cli::cli_inform(c(
+      i = "Installing {.pkg {pkg$package}} in temporary library"
+    ))
+  }
   withr::local_temp_libpaths(.local_envir = env)
   install(pkg, upgrade = FALSE, reload = FALSE, quick = TRUE, quiet = quiet)
 }

_pkgdown.yml

@@ -20,7 +20,7 @@ reference:
   contents:
   - build
   - build_manual
-  - build_rmd
+  - build_readme
   - build_site
   - starts_with("check_")
   - check
@@ -46,6 +46,7 @@ reference:
 - title: Deprecated
   contents:
   - bash
+  - build_rmd
   - build_vignettes
   - clean_vignettes
   - create

man/build_readme.Rd

@@ -14,3 +14,12 @@
       Error in `build_readme()`:
       ! Can't have both 'README.Rmd' and 'inst/README.Rmd'.
 
+# build_rmd() is deprecated
+
+    Code
+      suppressMessages(build_rmd("README.Rmd", path = pkg, quiet = TRUE))
+    Condition
+      Warning:
+      `build_rmd()` was deprecated in devtools 2.5.0.
+      i Please use `build_readme()` instead.
+

man/build_rmd.Rd

@@ -2,9 +2,14 @@ test_that("can build README in root directory", {
   skip_on_cran()
 
   pkg <- local_package_create()
-  suppressMessages(usethis::with_project(pkg, use_readme_rmd()))
+  usethis::ui_silence(
+    usethis::with_project(
+      pkg,
+      use_readme_rmd(open = FALSE)
+    )
+  )
 
-  suppressMessages(build_readme(pkg))
+  build_readme(pkg, quiet = TRUE)
   expect_true(file_exists(path(pkg, "README.md")))
   expect_false(file_exists(path(pkg, "README.html")))
 })
@@ -13,14 +18,19 @@ test_that("can build README in inst/", {
   skip_on_cran()
 
   pkg <- local_package_create()
-  suppressMessages(usethis::with_project(pkg, use_readme_rmd()))
+  usethis::ui_silence(
+    usethis::with_project(
+      pkg,
+      use_readme_rmd(open = FALSE)
+    )
+  )
   dir_create(pkg, "inst")
   file_move(
     path(pkg, "README.Rmd"),
     path(pkg, "inst", "README.Rmd")
   )
 
-  suppressMessages(build_readme(pkg))
+  build_readme(pkg, quiet = TRUE)
   expect_true(file_exists(path(pkg, "inst", "README.md")))
   expect_false(file_exists(path(pkg, "README.Rmd")))
   expect_false(file_exists(path(pkg, "README.md")))
@@ -31,7 +41,12 @@ test_that("useful errors if too few or too many", {
   pkg <- local_package_create()
   expect_snapshot(build_readme(pkg), error = TRUE)
 
-  suppressMessages(usethis::with_project(pkg, use_readme_rmd()))
+  usethis::ui_silence(
+    usethis::with_project(
+      pkg,
+      use_readme_rmd(open = FALSE)
+    )
+  )
   dir_create(pkg, "inst")
   file_copy(path(pkg, "README.Rmd"), path(pkg, "inst", "README.Rmd"))
   expect_snapshot(build_readme(pkg), error = TRUE)
@@ -41,9 +56,35 @@ test_that("don't error for README in another directory", {
   skip_on_cran()
 
   pkg <- local_package_create()
-  suppressMessages(usethis::with_project(pkg, use_readme_rmd(open = FALSE)))
+  usethis::ui_silence(
+    usethis::with_project(
+      pkg,
+      use_readme_rmd(open = FALSE)
+    )
+  )
   dir_create(pkg, "data-raw")
   file_create(pkg, "data-raw", "README.md")
 
-  expect_no_error(suppressMessages(build_readme(pkg)))
+  expect_no_error(build_readme(pkg, quiet = TRUE))
+})
+
+test_that("build_rmd() is deprecated", {
+  skip_on_cran()
+
+  pkg <- local_package_create()
+  usethis::ui_silence(
+    usethis::with_project(
+      pkg,
+      use_readme_rmd(open = FALSE)
+    )
+  )
+
+  withr::local_options(lifecycle_verbosity = "warning")
+  # it's hard (impossible?) to silence pak (cli, really) so that's what the
+  # suppressMessages() is for
+  expect_snapshot(suppressMessages(build_rmd(
+    "README.Rmd",
+    path = pkg,
+    quiet = TRUE
+  )))
 })