Close #2175. Improve installation docs and warnings/errors surroundin…

…g save_image() (#2360)

DESCRIPTION

@@ -42,7 +42,7 @@ Imports:
     vctrs,
     tibble,
     lazyeval (>= 0.2.0),
-    rlang (>= 0.4.10),
+    rlang (>= 1.0.0),
     crosstalk,
     purrr,
     data.table,

R/export.R

@@ -1,6 +1,6 @@
 #' Export a plotly graph to a static file
 #' 
-#' This function is in the process of being deprecated (use [orca] instead).
+#' This function is deprecated, use [save_image] instead.
 #' 
 #' @details For SVG plots, a screenshot is taken via `webshot::webshot()`.
 #' Since `phantomjs` (and hence `webshot`) does not support WebGL,
@@ -19,7 +19,7 @@
 #' @author Carson Sievert
 #'
 export <- function(p = last_plot(), file = "plotly.png", selenium = NULL, ...) {
-  .Deprecated("orca")
+  .Deprecated("save_image")
 
   # infer the file type
   fileType <- tolower(tools::file_ext(file))

R/kaleido.R

@@ -8,14 +8,15 @@
 #' @section Installation:
 #' 
 #' `kaleido()` requires [the kaleido python
-#' package](https://github.com/plotly/Kaleido/) to be usable via the \pkg{reticulate} package. Here is a recommended way to do the installation:
+#' package](https://github.com/plotly/Kaleido/) to be usable via the
+#' \pkg{reticulate} package. If you're starting from scratch, you install
+#' eveything you need with the following R code:
 #' 
 #' ```
-#' install.packages('reticulate')
-#' reticulate::install_miniconda()
-#' reticulate::conda_install('r-reticulate', 'python-kaleido')
-#' reticulate::conda_install('r-reticulate', 'plotly', channel = 'plotly')
-#' reticulate::use_miniconda('r-reticulate')
+#' install.packages("reticulate")
+#' library(reticulate)
+#' use_python(install_python())
+#' py_install(c("kaleido", "plotly"))
 #' ```
 #' 
 #' @param ... not currently used.
@@ -65,16 +66,40 @@ save_image <- function(p, file, ..., width = NULL, height = NULL, scale = NULL)
 #' @rdname save_image
 #' @export
 kaleido <- function(...) {
-  if (!rlang::is_installed("reticulate")) {
-    stop("`kaleido()` requires the reticulate package.")
-  }
-  if (!reticulate::py_available(initialize = TRUE)) {
-    stop("`kaleido()` requires `reticulate::py_available()`  to be `TRUE`. Do you need to install python?")
+  rlang::check_installed("reticulate")
+
+  call_env <- rlang::caller_env()
+
+  if (!reticulate::py_available()) {
+    rlang::abort(c("`{reticulate}` wasn't able to find a Python environment.",
+      i = "If you have an existing Python installation, use `reticulate::use_python()` to inform `{reticulate}` of it.",
+      i = "To have `{reticulate}` install Python for you, `reticulate::install_python()`."
+    ), call = call_env)
   }
 
+  tryCatch(
+    reticulate::import("plotly"),
+    error = function(e) {
+      rlang::abort(c(
+        "The `plotly` Python package is required for static image exporting.",
+        i = "Please install it via `reticulate::py_install('plotly')`."
+      ), call = call_env)
+    }
+  )
+
+  kaleido <- tryCatch(
+    reticulate::import("kaleido"),
+    error = function(e) {
+      rlang::abort(c(
+        "The `kaleido` Python package is required for static image exporting.",
+        i = "Please install it via `reticulate::py_install('kaleido')`."
+      ), call = call_env)
+    }
+  )
+
   py <- reticulate::py
   scope_name <- paste0("scope_", new_id())
-  py[[scope_name]] <- reticulate::import("kaleido")$scopes$plotly$PlotlyScope(
+  py[[scope_name]] <- kaleido$scopes$plotly$PlotlyScope(
     plotlyjs = plotlyMainBundlePath()
   )
 

R/orca.R

@@ -1,6 +1,6 @@
 #' Static image exporting via orca
 #' 
-#' Superseded by [kaleido()].
+#' This function is deprecated, use [save_image()] instead.
 #' 
 #' @param p a plotly object.
 #' @param file output filename.
@@ -60,7 +60,7 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
                  parallel_limit = NULL, verbose = FALSE, debug = FALSE, 
                  safe = FALSE, more_args = NULL, ...) {
 
-  .Deprecated("kaleido")
+  .Deprecated("save_image")
 
   orca_available()