Improve installation docs and warnings/errors surrounding save_image()

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()