Issue with documentation regarding python requirements

[mmahmoudian]

The issue in one sentence

Documentation and error messages are badly misleading.

Elaboration on the issue

In the documentation, especially ?plotly::save_image, there is extra and unnecessary focus on miniconda, and also on all the error messages of plotly::save_image(). This is despite the fact that python is practically pre-installed on all Linux distros and almost all macOS setups.

Additionally, there are two related issues:

1. deprecated functions send user to a rabbit-hole rather than pointing them to the function they should use (export() -> orca() -> kaleido() -> Deadend, but ?kaleido -> save_image())
2. the save_image() does not check availability of all the python modules and dependencies and the user has to go through a step-wise process of getting error, installing the next missing one and etc.

In the following, I have showed the reasoning and the journey I went through to get this working:

---

For the following, I have used the verbatim code from here:
https://plotly.com/r/violin/#split-violin-plot#advanced-violin-plot

1. Following some online tutorial I figured I can use:

plotly::export(p = fig, file = "aa.svg")

Error: Must provide an object of class 'rsClientServer' to the `selenium` argument to export this plot (see examples section on `help(export)`)
In addition: Warning messages:
1: 'plotly::export' is deprecated.
Use 'orca' instead.
See help("Deprecated") 

2. Ah, deprecated. So let's try orca():

plotly::orca(p = fig, file = "aa.svg")

Error: The orca command-line utility is required for this functionality.

Please follow the installation instructions here -- https://github.com/plotly/orca#installation
In addition: Warning message:
'plotly::orca' is deprecated.
Use 'kaleido' instead.
See help("Deprecated") 

3. Oh, deprecated too! let's see how the kaleido should be used. Well, ?kaleido shows that the save_image() should be used, so let's see

plotly::save_image(p = fig, file = "aa.svg")

No non-system installation of Python could be found.
Would you like to download and install Miniconda?
Miniconda is an open source environment management system for Python.
See https://docs.conda.io/en/latest/miniconda.html for more details.

Would you like to install Miniconda? [Y/n]: n
Installation aborted.
Error in py_module_import(module, convert = convert) : 
  ModuleNotFoundError: No module named 'kaleido'

The python is already there, so the error "No non-system installation of Python could be found." is nonsensical:

❯  python --version
Python 3.10.5

❯  which python 
/usr/bin/python

❯  ls -alh $(which python)
lrwxrwxrwx 1 root root 7 Aug  1 10:53 /usr/bin/python -> python3

This is a bad situation and it took me a while to understand what the issue is: lack of the reticulate R package so that R can talk to python. I wonder why this is not a dependency of the plotly R package!

install.packages("reticulate")

4. Now that R can talk with python (again, minoconda is NOT NEEDED), let's try again:

plotly::save_image(p = fig, file = "aa.svg")

Error in py_module_import(module, convert = convert) : 
  ModuleNotFoundError: No module named 'kaleido'

The error is clear, but not user-friendly because it does not clarify to user that this is a python thing (apart from py_ in the function name). Regardless, I installed it:

❯  pip install kaleido

5. Try again...

plotly::save_image(p = fig, file = "graph 1.svg")

Error in py_run_string_impl(code, local, convert) : 
  ModuleNotFoundError: No module named 'plotly'

Same user-friendliness complaint as above.

❯  pip install plotly

6. Now it works!

---

System info

• plotly 4.10.0 2021-10-09 CRAN (R 4.1.0)
• reticulate 1.25 2022-05-11 [1] CRAN (R 4.1.2)
• R version 4.1.2 (2021-11-01)
• rstudio 2022.02.2+485 Prairie Trillium (server)
• OS: Manjaro Linux

Please let me know if you need further information

[serkor1]

Running on Ubuntu 22.04 - followed all your steps. I am still not past the error-message:

Error in py_module_import(module, convert = convert) : 
  ModuleNotFoundError: No module named 'kaleido'

I miss the webshot()-wrapper plotly::export()-function to be honest.