Merge branch 'main' into drop-superseded-ui

Author: jennybc

DESCRIPTION

@@ -35,11 +35,8 @@ Imports:
     roxygen2 (>= 7.3.3),
     rversions (>= 2.1.2),
     sessioninfo (>= 1.2.3),
-    stats,
     testthat (>= 3.2.3),
-    tools,
     urlchecker (>= 1.0.1),
-    utils,
     withr (>= 3.0.2)
 Suggests:
     BiocManager (>= 1.30.18),
@@ -50,14 +47,9 @@ Suggests:
     DT (>= 0.23),
     foghorn (>= 1.4.2),
     gh (>= 1.3.0),
-    gmailr (>= 1.0.1),
     httr (>= 1.4.3),
     knitr (>= 1.39),
     lintr (>= 3.0.0),
-    MASS,
-    mockery (>= 0.4.3),
-    pingr (>= 2.0.1),
-    rhub (>= 1.1.1),
     rmarkdown (>= 2.14),
     rstudioapi (>= 0.13),
     spelling (>= 2.2)

NAMESPACE

@@ -13,6 +13,7 @@ export(build_vignettes)
 export(check)
 export(check_built)
 export(check_dep_version)
+export(check_doc_fields)
 export(check_mac_devel)
 export(check_mac_release)
 export(check_man)
@@ -82,8 +83,6 @@ export(uses_testthat)
 export(wd)
 export(with_debug)
 import(fs)
-importFrom(cli,cat_bullet)
-importFrom(cli,cat_rule)
 importFrom(ellipsis,check_dots_used)
 importFrom(lifecycle,deprecated)
 importFrom(memoise,memoise)
@@ -95,30 +94,7 @@ importFrom(pkgload,check_dep_version)
 importFrom(pkgload,is_loading)
 importFrom(pkgload,parse_deps)
 importFrom(pkgload,unload)
-importFrom(remotes,dev_package_deps)
-importFrom(remotes,github_pull)
-importFrom(remotes,github_release)
-importFrom(remotes,install_bioc)
-importFrom(remotes,install_bitbucket)
-importFrom(remotes,install_cran)
-importFrom(remotes,install_dev)
-importFrom(remotes,install_git)
-importFrom(remotes,install_github)
-importFrom(remotes,install_gitlab)
-importFrom(remotes,install_local)
-importFrom(remotes,install_svn)
-importFrom(remotes,install_url)
-importFrom(remotes,install_version)
-importFrom(remotes,update_packages)
 importFrom(sessioninfo,package_info)
 importFrom(sessioninfo,session_info)
 importFrom(stats,update)
 importFrom(usethis,use_test)
-importFrom(utils,available.packages)
-importFrom(utils,contrib.url)
-importFrom(utils,install.packages)
-importFrom(utils,installed.packages)
-importFrom(utils,modifyList)
-importFrom(utils,packageDescription)
-importFrom(utils,packageVersion)
-importFrom(utils,remove.packages)

NEWS.md

@@ -1,15 +1,21 @@
 # devtools (development version)
 
+* `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).
+* `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).
 * 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 uses cli for user-facing messages instead of deprecated usethis UI functions.
 * `dev_sitrep()` now works correctly in Positron (#2618).
 * `is_loading()` is now re-exported from pkgload (#2556).
+* Package installation functions are now deprecated: `install_bioc()`, `install_bitbucket()`, `install_cran()`, `install_deps()`, `install_dev()`, `install_dev_deps()`, `install_git()`, `install_github()`, `install_gitlab()`, `install_local()`, `install_svn()`, `install_url()`, `install_version()`, `update_packages()`, `dev_package_deps()`, `github_pull()`, and `github_release()`. We now recommend pak (<https://pak.r-lib.org/>) for general package installation. See `?install-deprecated` for migration guidance.
 * `load_all()` now errors if called recursively, i.e. if you accidentally include a `load_all()` call in one of your R source files (#2617).
 * `release()` is deprecated in favour of `usethis::use_release_issue()`.
 * `show_news()` now looks for NEWS files in the same locations as `utils::news()`: `inst/NEWS.Rd`, `NEWS.md`, `NEWS`, and `inst/NEWS` (@arcresu, #2499).
+* `test_active_file()` now works when the active file is a snapshot file.
+* `test_coverage()` and `test_coverage_active_file()` gain a new `report` argument that can be set to `"html"` (the default, for an interactive browser report), `"zero"` (prints uncovered lines to the console, used for LLMs and non-interactive contexts), or `"silent"`. The `show_report` argument has been removed (#2632).
+* `test_file()` and `test_coverage_file()` are now defunct. These were deprecated in devtools 2.4.0 (2021-04-07) in favour of `test_active_file()` and `test_coverage_active_file()`. Removing `test_file()` eliminates the conflict with `testthat::test_file()`.
 
 # devtools 2.4.6
 

R/active.R

@@ -37,6 +37,8 @@ find_test_file <- function(path, call = parent.frame()) {
 
 test_file_type <- function(path) {
   dir <- path_file(path_dir(path))
+  # this accounts for snapshot files in a variant subfolder
+  parent_dir <- path_file(path_dir(path_dir(path)))
   name <- path_file(path)
   ext <- tolower(path_ext(path))
 
@@ -46,6 +48,8 @@ test_file_type <- function(path) {
   type[dir == "R" & ext == "r"] <- "R"
   type[dir == "testthat" & ext == "r" & grepl("^test", name)] <- "test"
   type[dir == "src" & ext %in% src_ext] <- "src"
+  type[dir == "_snaps" & ext == "md"] <- "snap"
+  type[parent_dir == "_snaps" & ext == "md"] <- "snap"
   type
 }
 

R/bash.R

@@ -1,8 +1,16 @@
 #' Open bash shell in package directory
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `bash()` is deprecated because we no longer use or recommend this workflow.
+#' Open bash shell in package directory
+#'
 #' @template devtools
 #' @export
+#' @keywords internal
 bash <- function(pkg = ".") {
+  lifecycle::deprecate_warn("2.5.0", "bash()")
   pkg <- as.package(pkg)
 
   withr::with_dir(pkg$path, system("bash"))

R/check-devtools.R

@@ -8,15 +8,15 @@
 #' @export
 release_checks <- function(pkg = ".", built_path = NULL) {
   pkg <- as.package(pkg)
-  cat_rule(paste0("Running additional devtools checks for ", pkg$package))
+  cli::cat_rule(paste0("Running additional devtools checks for ", pkg$package))
 
   check_version(pkg)
   check_dev_versions(pkg)
   check_vignette_titles(pkg)
   check_news_md(pkg)
   check_remotes(pkg)
 
-  cat_rule()
+  cli::cat_rule()
 }
 
 check_dev_versions <- function(pkg = ".") {

R/check-doc.R

@@ -62,3 +62,54 @@ man_message <- function(x) {
     FALSE
   }
 }
+
+#' Check for missing documentation fields
+#'
+#' Checks all Rd files in `man/` and looks for any that have a `\usage` section
+#' (i.e. a function) but that *don't* have `\value` and `\examples` sections.
+#' These missing fields are flagged by CRAN on initial submission.
+#'
+#' @template devtools
+#' @param fields A character vector of Rd field names to check for.
+#' @returns A named list of character vectors, one for each field, containing
+#'   the names of Rd files missing that field. Returned invisibly.
+#' @export
+#' @examples
+#' \dontrun{
+#' check_doc_fields(".")
+#' }
+check_doc_fields <- function(pkg = ".", fields = c("value", "examples")) {
+  pkg <- as.package(pkg)
+  fields <- stats::setNames(fields, fields)
+
+  paths <- dir_ls(path(pkg$path, "man"), regexp = "\\.Rd$")
+  names(paths) <- path_rel(paths, pkg$path)
+  rd <- lapply(paths, tools::parse_Rd, permissive = TRUE)
+  rd_tags <- lapply(rd, \(x) unlist(lapply(x, attr, "Rd_tag")))
+
+  has_tag <- function(tags, this) {
+    any(paste0("\\", this) %in% tags)
+  }
+
+  has_usage <- vapply(rd_tags, has_tag, logical(1), this = "usage")
+  rd_tags <- rd_tags[has_usage]
+
+  results <- lapply(fields, function(field) {
+    missing <- !vapply(rd_tags, has_tag, logical(1), this = field)
+    names(rd_tags)[missing]
+  })
+
+  for (field in fields) {
+    missing <- results[[field]]
+    if (length(missing) > 0) {
+      cli::cli_inform(c(
+        "!" = "Missing {.code \\{field}} section in {length(missing)} file{?s}:",
+        stats::setNames(missing, rep("*", length(missing)))
+      ))
+    } else {
+      cli::cli_inform(c("v" = "All Rd files have a {.code \\{field}} section."))
+    }
+  }
+
+  invisible(results)
+}

R/check-git.R

@@ -7,11 +7,11 @@
 #' @keywords internal
 git_checks <- function(pkg = ".") {
   pkg <- as.package(pkg)
-  cat_rule(paste0("Running Git checks for ", pkg$package))
+  cli::cat_rule(paste0("Running Git checks for ", pkg$package))
 
   git_report_branch(pkg)
   git_check_uncommitted(pkg)
-  cat_rule()
+  cli::cat_rule()
 }
 
 git_report_branch <- function(pkg) {

R/check.R

@@ -85,7 +85,7 @@ check <- function(
   document <- document %||% can_document(pkg$roxygennote)
   if (document) {
     if (!quiet) {
-      cat_rule("Documenting", col = "cyan", line = 2)
+      cli::cat_rule("Documenting", col = "cyan", line = 2)
     }
     document(pkg, quiet = quiet)
     if (!quiet) {
@@ -94,7 +94,7 @@ check <- function(
   }
 
   if (!quiet) {
-    cat_rule("Building", col = "cyan", line = 2)
+    cli::cat_rule("Building", col = "cyan", line = 2)
     show_env_vars(pkgbuild::compiler_flags(FALSE))
   }
 
@@ -133,7 +133,7 @@ check <- function(
   )
 }
 
-can_document <- function(required, installed = packageVersion("roxygen2")) {
+can_document <- function(required, installed = utils::packageVersion("roxygen2")) {
   if (is.null(required)) {
     return(FALSE)
   }
@@ -222,7 +222,7 @@ check_built <- function(
 
   env_vars <- check_env_vars(cran, remote, incoming, force_suggests, env_vars)
   if (!quiet) {
-    cat_rule("Checking", col = "cyan", line = 2)
+    cli::cat_rule("Checking", col = "cyan", line = 2)
     show_env_vars(env_vars)
   }
 
@@ -271,7 +271,7 @@ aspell_env_var <- function() {
 
 show_env_vars <- function(env_vars) {
   cli::cat_line("Setting env vars:", col = "darkgrey")
-  cat_bullet(
+  cli::cat_bullet(
     paste0(format(names(env_vars)), ": ", unname(env_vars)),
     col = "darkgrey"
   )

R/create.R

@@ -1,11 +1,19 @@
 #' Create a package
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `create()` is deprecated. Please use [usethis::create_package()] directly
+#' instead.
+#'
 #' @param path A path. If it exists, it is used. If it does not exist, it is
 #'   created, provided that the parent path exists.
 #' @param ... Additional arguments passed to [usethis::create_package()]
 #' @inheritParams usethis::create_package
 #' @return The path to the created package, invisibly.
 #' @export
+#' @keywords internal
 create <- function(path, ..., open = FALSE) {
+  lifecycle::deprecate_warn("2.5.0", "create()", "usethis::create_package()")
   usethis::create_package(path, ..., open = open)
 }