From 2caf6258dfd8e28a9083df5ac496800f70b0a92a Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Mon, 10 Jun 2024 13:51:33 -0500
Subject: [PATCH] Improve preview docs/tests/implementation (#2650)

---
 NEWS.md                          |  1 +
 R/preview.R                      | 35 ++++++++++++++++++++++++--------
 man/preview_page.Rd              |  3 +--
 man/preview_site.Rd              |  5 ++++-
 tests/testthat/_snaps/preview.md |  5 +++++
 tests/testthat/test-preview.R    | 16 +++++++++++++++
 6 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index ad5bba889..4e800a793 100644
--- a/NEWS.md
+++ b/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.
diff --git a/R/preview.R b/R/preview.R
index 4200f498a..6c84e503f 100644
--- a/R/preview.R
+++ b/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() {
diff --git a/man/preview_page.Rd b/man/preview_page.Rd
index 32ddc627b..c1c929fd5 100644
--- a/man/preview_page.Rd
+++ b/man/preview_page.Rd
@@ -7,7 +7,6 @@
 preview_page(path, pkg = ".")
 }
 \description{
-Only works when rendering the working directory, as this is the most
-common interactive workflow.
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{\link[=preview_site]{preview_site()}} instead.
 }
 \keyword{internal}
diff --git a/man/preview_site.Rd b/man/preview_site.Rd
index 532983386..d12fb6750 100644
--- a/man/preview_site.Rd
+++ b/man/preview_site.Rd
@@ -15,5 +15,8 @@ preview_site(pkg = ".", path = ".", preview = TRUE)
 freshly generated section in browser.}
 }
 \description{
-Open site in browser
+\code{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 \code{servr::httw("docs/")}
+to create a server to make search work locally.
 }
diff --git a/tests/testthat/_snaps/preview.md b/tests/testthat/_snaps/preview.md
index 84b9cb23e..fcef0e918 100644
--- a/tests/testthat/_snaps/preview.md
+++ b/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
diff --git a/tests/testthat/test-preview.R b/tests/testthat/test-preview.R
index ffaf0fe6b..e83424178 100644
--- a/tests/testthat/test-preview.R
+++ b/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")
+  ) 
+})