Improve preview docs/tests/implementation (#2650)

NEWS.md

@@ -1,5 +1,6 @@
 # pkgdown (development version)
 
+* `preivew_page()` has been deprecated (#2650).
 * `build_article()` now translates the "Abstract" title if it's used.
 * `build_*()` (apart from `build_site()`) functions no longer default to previewing in interactive sessions since they now all emit specific links to newly generated files.
 * `document` in `build_site()` and `build_reference()` has been removed after being deprecated in pkgdown 1.4.0. `devel` should be used instead.

R/preview.R

@@ -1,35 +1,54 @@
 #' Open site in browser
 #'
+#' `preview_site()` opens your pkgdown site in your browser. pkgdown has been
+#' carefully designed to work even when served from the file system like 
+#' this; the only part that doesn't work is search. You can use `servr::httw("docs/")` 
+#'  to create a server to make search work locally.
+#' 
 #' @inheritParams build_article
 #' @param path Path relative to destination
 #' @export
 preview_site <- function(pkg = ".", path = ".", preview = TRUE) {
-  pkg <- as_pkgdown(pkg)
-  check_string(path)
+  path <- local_path(pkg, path)
+
   check_bool(preview, allow_na = TRUE)
-
   if (is.na(preview)) {
     preview <- interactive() && !is_testing()
   }
 
   if (preview) {
     cli::cli_inform(c(i = "Previewing site"))
-    utils::browseURL(path(pkg$dst_path, path, "index.html"))
+    utils::browseURL(path)
   }
 
   invisible()
 }
 
+local_path <- function(pkg, path, call = caller_env()) {
+  pkg <- as_pkgdown(pkg)
+  check_string(path, call = call)
+
+  abs_path <- path_abs(path, pkg$dst_path)
+  if (!file_exists(abs_path)) {
+    cli::cli_abort("Can't find file {.path {path}}.", call = call)
+  }
+
+  if (is_dir(abs_path)) {
+    abs_path <- path(abs_path, "index.html")
+  }
+  abs_path
+}
+
 #' Preview a local pkgdown page in the browser
 #'
-#' Only works when rendering the working directory, as this is the most
-#' common interactive workflow.
+#' @description
+#' `r lifecycle::badge("deprecated")` Use [preview_site()] instead.
 #'
 #' @export
 #' @keywords internal
 preview_page <- function(path, pkg = ".") {
-  pkg <- as_pkgdown(".")
-  utils::browseURL(path_abs(path(pkg$dst_path, path)))
+  lifecycle::deprecate_warn("2.1.0", "preview_page()", "preview_site()")
+  preview_site(pkg, path, preview = TRUE)
 }
 
 is_testing <- function() {

tests/testthat/_snaps/preview.md

@@ -5,6 +5,11 @@
     Condition
       Error in `preview_site()`:
       ! `path` must be a single string, not the number 1.
+    Code
+      preview_site(pkg, path = "foo")
+    Condition
+      Error in `preview_site()`:
+      ! Can't find file 'foo'.
     Code
       preview_site(pkg, preview = 1)
     Condition

tests/testthat/test-preview.R

@@ -3,6 +3,22 @@ test_that("checks its inputs", {
 
   expect_snapshot(error = TRUE, {
     preview_site(pkg, path = 1)
+    preview_site(pkg, path = "foo")
     preview_site(pkg, preview = 1)
   })
 })
+
+test_that("local_path adds index.html if needed", {
+  pkg <- local_pkgdown_site()
+  file_create(path(pkg$dst_path, "test.html"))
+  expect_equal(
+    local_path(pkg, "test.html"),
+    path(pkg$dst_path, "test.html")
+  )
+
+  dir_create(path(pkg$dst_path, "reference"))
+  expect_equal(
+    local_path(pkg, "reference"),
+    path(pkg$dst_path, "reference", "index.html")
+  ) 
+})