Deprecate build_vignettes() and clean_vignettes() (#2648)

Fixes #2488

Author: hadley

NEWS.md

@@ -1,6 +1,7 @@
 # devtools (development version)
 
 * `build_manual()` reports more details on failure (#2586).
+* `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).
 * New `check_mac_devel()` function to check a package using the macOS builder at https://mac.r-project.org/macbuilder/submit.html (@nfrerebeau, #2507)
 * `dev_sitrep()` now works correctly in Positron (#2618).

R/vignettes.R

@@ -1,14 +1,12 @@
-#' Build package vignettes.
+#' Build package vignettes
 #'
-#' Builds package vignettes using the same algorithm that `R CMD build`
-#' does. This means including non-Sweave vignettes, using makefiles (if
-#' present), and copying over extra files. The files are copied in the 'doc'
-#' directory and an vignette index is created in 'Meta/vignette.rds', as they
-#' would be in a built package. 'doc' and 'Meta' are added to
-#' `.Rbuildignore`, so will not be included in the built package. These
-#' files can be checked into version control, so they can be viewed with
-#' `browseVignettes()` and `vignette()` if the package has been
-#' loaded with `load_all()` without needing to re-build them locally.
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `build_vignettes()` is deprecated because we no longer recommend that you
+#' build vignettes in this way, because it leaves build artifacts in your
+#' development directory. Instead, use [pkgdown::build_article()] to
+#' render articles locally for preview and polishing.
 #'
 #' @template devtools
 #' @param quiet If `TRUE`, suppresses most output. Set to `FALSE`
@@ -22,11 +20,8 @@
 #' @inheritParams tools::buildVignettes
 #' @inheritParams remotes::install_deps
 #' @importFrom stats update
-#' @keywords programming
-#' @seealso [clean_vignettes()] to remove the pdfs in
-#'   \file{doc} created from vignettes
+#' @keywords internal
 #' @export
-#' @seealso [clean_vignettes()] to remove build tex/pdf files.
 build_vignettes <- function(
   pkg = ".",
   dependencies = "VignetteBuilder",
@@ -36,12 +31,13 @@ build_vignettes <- function(
   install = TRUE,
   keep_md = TRUE
 ) {
+  lifecycle::deprecate_warn("2.5.0", "build_vignettes()")
   pkg <- as.package(pkg)
   save_all()
 
   vigns <- tools::pkgVignettes(dir = pkg$path)
   if (length(vigns$docs) == 0) {
-    return()
+    return(invisible())
   }
 
   deps <- remotes::dev_package_deps(pkg$path, dependencies)
@@ -86,18 +82,22 @@ create_vignette_index <- function(pkg, vigns) {
   saveRDS(vignette_index, vignette_index_path, version = 2L)
 }
 
-#' Clean built vignettes.
+#' Clean built vignettes
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
 #'
-#' This uses a fairly rudimentary algorithm where any files in \file{doc}
-#' with a name that exists in \file{vignettes} are removed.
+#' `clean_vignettes()` is deprecated because [build_vignettes()] is deprecated.
 #'
 #' @template devtools
+#' @keywords internal
 #' @export
 clean_vignettes <- function(pkg = ".") {
+  lifecycle::deprecate_warn("2.5.0", "clean_vignettes()")
   pkg <- as.package(pkg)
   vigns <- tools::pkgVignettes(dir = pkg$path)
-  if (path_file(vigns$dir) != "vignettes") {
-    return()
+  if (length(vigns$docs) == 0 || path_file(vigns$dir) != "vignettes") {
+    return(invisible())
   }
 
   cli::cli_inform(c(

_pkgdown.yml

@@ -19,7 +19,9 @@ reference:
   desc: Primary commands used when developing a package.
   contents:
   - build
-  - starts_with("build_")
+  - build_manual
+  - build_rmd
+  - build_site
   - starts_with("check_")
   - check
   - create
@@ -35,7 +37,6 @@ reference:
 - title: Utilities
   contents:
   - bash
-  - clean_vignettes
   - dev_sitrep
   - github_pull
   - lint
@@ -47,9 +48,10 @@ reference:
   - update_packages
   - wd
   - save_all
-
 - title: Deprecated functions
   contents:
+  - build_vignettes
+  - clean_vignettes
   - release
 
 news:

man/build_vignettes.Rd

@@ -0,0 +1,13 @@
+# build_vignettes() and clean_vignettes() are deprecated
+
+    Code
+      build_vignettes(pkg)
+    Condition
+      Warning:
+      `build_vignettes()` was deprecated in devtools 2.5.0.
+    Code
+      clean_vignettes(pkg)
+    Condition
+      Warning:
+      `clean_vignettes()` was deprecated in devtools 2.5.0.
+

man/clean_vignettes.Rd

@@ -1,4 +1,5 @@
 test_that("Sweave vignettes copied into doc", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   if (!pkgbuild::has_latex()) {
     skip("pdflatex not available")
   }
@@ -13,6 +14,7 @@ test_that("Sweave vignettes copied into doc", {
 })
 
 test_that("Built files are updated", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   # This test is time dependant and sometimes fails on CRAN because the systems are under heavy load.
   skip_on_cran()
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
@@ -29,6 +31,7 @@ test_that("Built files are updated", {
 })
 
 test_that("Rmarkdown vignettes copied into doc", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
   doc <- path(pkg, "doc")
 
@@ -37,6 +40,7 @@ test_that("Rmarkdown vignettes copied into doc", {
 })
 
 test_that("extra files copied and removed", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
   writeLines("a <- 1", path(pkg, "vignettes", "a.R"))
 
@@ -51,9 +55,18 @@ test_that("extra files copied and removed", {
 })
 
 test_that(".gitignore updated when building vignettes", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   pkg <- local_package_copy(test_path("testMarkdownVignettes"))
   gitignore <- path(pkg, ".gitignore")
 
   suppressMessages(build_vignettes(pkg, quiet = TRUE))
   expect_true(all(c("/Meta/", "/doc/") %in% readLines(gitignore)))
 })
+
+test_that("build_vignettes() and clean_vignettes() are deprecated", {
+  pkg <- local_package_create()
+  expect_snapshot({
+    build_vignettes(pkg)
+    clean_vignettes(pkg)
+  })
+})