Make devel = FALSE stricter (#1116)

Now installs package in temporary environment (which you can opt out of with `install = FALSE`). Also removes knitting code from `build_home()`, since that touches files outside of `doc/`.

Fixes #1061

NEWS.md

@@ -3,14 +3,22 @@
 ## New features
 
 * `build_site()`, `build_reference()` and `build_home()` gain a parameter 
-  `devel` which can be set to `FALSE` to disable redocumenting and reloading 
-  the package, and knitting of home `Rmd` file. This generalises and replaces 
-  (with deprecation) the existing `document` argument.
-
-    `build_reference()` no longer automatically runs `devtools::document()` 
-    when `devel`/`document` is `TRUE` (#1079). This makes the scope of 
-    responsibility of pkgdown more clear: it now only creates/modifies 
-    files in `doc/`.
+  `devel` which controls whether you're in deployment or development mode.
+  It generalises and replaces (with deprecation) the existing `document` 
+  argument.
+
+    Development mode is optimised for rapid iteration and is the default
+    for `build_reference()`. It uses `pkgload::load_all()` to load code
+    directly from disk in order.
+
+    Deployment mode is slower, but guarantees correct results, and is the
+    default for `build_site()`. It installs the package into a temporary
+    library, and runs examples/articles in a new process.
+
+* `build_reference()` no longer runs `devtools::document()` (#1079) and
+  `build_home() no longer re-builds `README.Rmd`.  This makes the scope 
+  of responsibility of pkgdown more clear: it now only creates/modifies 
+  files in `doc/`.
 
 * `build_home()` now strips quotes from `Title` and `Description` fields 
   when generating page metadata. Additionally, you can now override the defaults 

R/build-home-index.R

@@ -1,35 +1,21 @@
-build_home_index <- function(pkg = ".", quiet = TRUE, knit = TRUE) {
+build_home_index <- function(pkg = ".", quiet = TRUE) {
   pkg <- as_pkgdown(pkg)
 
   scoped_package_context(pkg$package, pkg$topic_index, pkg$article_index)
   scoped_file_context(depth = 0L)
 
-  # When knit = FALSE, prefer pre-rendered md file if exists
-  src_path <- path_first_existing(
-    pkg$src_path,
-    if (knit){
-      c("index.Rmd", "README.Rmd", "index.md", "README.md")
-    } else {
-      c("index.md", "README.md","index.Rmd", "README.Rmd")
-    }
+  src_path <- path_first_existing(pkg$src_path,
+    c("index.md", "README.md", "index.Rmd", "README.Rmd")
   )
   dst_path <- path(pkg$dst_path, "index.html")
   data <- data_home(pkg)
 
   if (is.null(src_path)) {
     data$index <- linkify(pkg$desc$get("Description")[[1]])
-    render_page(pkg, "home", data, "index.html")
   } else {
-    file_ext <- path_ext(src_path)
-
-    if (file_ext == "md" || (!knit && file_ext == "Rmd")) {
-      data$index <- markdown(src_path)
-      render_page(pkg, "home", data, "index.html")
-    } else if (file_ext == "Rmd") {
-      data$index <- "$body$"
-      render_index(pkg, path_rel(src_path, pkg$src_path), data = data, quiet = quiet)
-    }
+    data$index <- markdown(src_path)
   }
+  render_page(pkg, "home", data, "index.html")
 
   strip_header <- isTRUE(pkg$meta$home$strip_header)
   update_html(dst_path, tweak_homepage_html, strip_header = strip_header)

R/build-home.R

@@ -1,10 +1,11 @@
 #' Build home section
 #'
-#' This function is responsible for building `.md` (or `.Rmd`) files typically
-#' found in the root directory of the package. It will generate the home page
-#' from  `index.Rmd` or `README.Rmd`, then `index.md` or `README.md`. If none of
-#' these are found, it falls back to the description field in `DESCRIPTION`. It
-#' also builds any files found in `.github/`.
+#' This function generates the home page, and converts other `.md` files
+#' typically found in the package root and in `.github/`. It generates the home
+#' page from  `index.md` or `README.md`, falling back to the description field
+#' in `DESCRIPTION` if neither is found. It also builds an authors page
+#' from the `DESCRIPTION` and `inst/CITATION` (if present) and
+#' a license page, and converts any `.md` files found in
 #'
 #' @section Images and figures:
 #' If you want to include images in your `README.md`, they must be stored
@@ -108,16 +109,11 @@
 #'   only contains images.
 #'
 #' @inheritParams build_articles
-#' @param devel If `TRUE`, assumes you are doing active development, and
-#'   re-knits all `.Rmd` files. If `FALSE`, assumes Rmarkdown files have
-#'   already rendered to `.md`, falling back to rendering as plain markdown
-#'   if they have not.
 #' @export
 build_home <- function(pkg = ".",
                        override = list(),
                        preview = NA,
-                       quiet = TRUE,
-                       devel = TRUE) {
+                       quiet = TRUE) {
 
   pkg <- section_init(pkg, depth = 0L, override = override)
   rule("Building home")
@@ -130,7 +126,7 @@ build_home <- function(pkg = ".",
   }
   build_home_md(pkg)
   build_home_license(pkg)
-  build_home_index(pkg, quiet = quiet, knit = devel)
+  build_home_index(pkg, quiet = quiet)
 
   preview_site(pkg, "/", preview = preview)
 }

R/build.r

@@ -261,9 +261,24 @@
 #' @inheritParams build_reference
 #' @param lazy If `TRUE`, will only rebuild articles and reference pages
 #'   if the source is newer than the destination.
+#' @param devel Use development or deployment process?
+#'
+#'   If `TRUE`, uses lighter-weight process suitable for rapid
+#'   iteration; it will run examples and vignettes in the current process,
+#'   and will load code with `pkgload::load_call()`.
+#'
+#'   If `FALSE`, will first install the package to a temporary library,
+#'   and will run all examples and vignettes in a new process.
+#'
+#'   `build_site()` defaults to `devel = FALSE` so that you get high fidelity
+#'   outputs when you building the complete site; `build_reference()`,
+#'   `build_home()` and friends default to `devel = TRUE` so that you can
+#'   rapidly iterate during development.
 #' @param new_process If `TRUE`, will run `build_site()` in a separate process.
 #'   This enhances reproducibility by ensuring nothing that you have loaded
 #'   in the current process affects the build process.
+#' @param install If `TRUE`, will install the package in a temporary library
+#'   so it is available for vignettes.
 #' @export
 #' @examples
 #' \dontrun{
@@ -278,15 +293,23 @@ build_site <- function(pkg = ".",
                        lazy = FALSE,
                        override = list(),
                        preview = NA,
-                       new_process = TRUE,
-                       devel = TRUE,
+                       devel = FALSE,
+                       new_process = !devel,
+                       install = !devel,
                        document = "DEPRECATED") {
+  pkg <- as_pkgdown(pkg)
 
   if (!missing(document)) {
     warning("`document` is deprecated. Please use `devel` instead.", call. = FALSE)
     devel <- document
   }
 
+  if (install) {
+    withr::local_temp_libpaths()
+    rule("Installing package into temporary library")
+    utils::install.packages(pkg$src_path, repo = NULL, type = "source", quiet = TRUE)
+  }
+
   if (new_process) {
     build_site_external(
       pkg = pkg,
@@ -370,7 +393,7 @@ build_site_local <- function(pkg = ".",
 
   init_site(pkg)
 
-  build_home(pkg, override = override, preview = FALSE, devel = devel)
+  build_home(pkg, override = override, preview = FALSE)
   build_reference(pkg,
     lazy = lazy,
     examples = examples,

R/deploy-site.R

@@ -122,6 +122,7 @@ deploy_local <- function(
     override = list(destination = dest_dir),
     devel = FALSE,
     preview = FALSE,
+    install = FALSE,
     ...
   )
   github_push(dest_dir, commit_message)