Update image export documentation to recommend and describe Kaleido

Author: jonmmease

doc/python/orca-management.md

@@ -34,13 +34,65 @@ jupyter:
 ---
 
 ### Overview
-This section covers the lower-level details of how plotly.py uses orca to perform static image generation. Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
+This section covers the lower-level details of how plotly.py can use orca to perform static image generation. Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
 
-### What is Orca?
+### What is orca?
 Orca is an [Electron](https://electronjs.org/) application that inputs plotly figure specifications and converts them into static images.  Orca can run as a command-line utility or as a long-running server process. In order to provide the fastest possible image export experience, plotly.py launches orca in server mode, and communicates with it over a local port. See https://github.com/plotly/orca for more information.
 
 By default, plotly.py launches the orca server process the first time an image export operation is performed, and then leaves it running until the main Python process exits. Because of this, the first image export operation in an interactive session will typically take a couple of seconds, but then all subsequent export operations will be significantly faster, since the server is already running.
 
+### Installing orca
+There are 3 general approaches to installing orca and its Python dependencies.
+
+##### conda
+Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command:
+```
+$ conda install -c plotly plotly-orca==1.2.1 psutil requests
+```
+
+**Note:** Even if you do not want to use conda to manage your Python dependencies, it is still useful as a cross platform tool for managing native libraries and command-line utilities (e.g. git, wget, graphviz, boost, gcc, nodejs, cairo, etc.).  For this use-case, start with [Miniconda](https://conda.io/miniconda.html) (~60MB) and tell the installer to add itself to your system `PATH`.  Then run `conda install plotly-orca==1.2.1` and the orca executable will be available system wide.
+
+##### npm + pip
+You can use the [npm](https://www.npmjs.com/get-npm) package manager to install `orca` (and its `electron` dependency), and then use pip to install `psutil`:
+
+```
+$ npm install -g electron@1.8.4 orca
+$ pip install psutil requests
+```
+
+##### Standalone Binaries + pip
+If you are unable to install conda or npm, you can install orca as a precompiled binary for your operating system. Follow the instructions in the orca [README](https://github.com/plotly/orca) to install orca and add it to your system `PATH`. Then use pip to install `psutil`.
+
+```
+$ pip install psutil requests
+```
+
+<!-- #region -->
+### Install orca on Google Colab
+```
+!pip install plotly>=4.7.1
+!wget https://github.com/plotly/orca/releases/download/v1.2.1/orca-1.2.1-x86_64.AppImage -O /usr/local/bin/orca
+!chmod +x /usr/local/bin/orca
+!apt-get install xvfb libgtk2.0-0 libgconf-2-4
+```
+
+Once this is done you can use this code to make, show and export a figure:
+
+```python
+import plotly.graph_objects as go
+fig = go.Figure( go.Scatter(x=[1,2,3], y=[1,3,2] ) )
+fig.write_image("fig1.svg")
+fig.write_image("fig1.png")
+```
+
+The files can then be downloaded with:
+
+```python
+from google.colab import files
+files.download('fig1.svg')
+files.download('fig1.png')
+```
+<!-- #endregion -->
 
 ### Create a Figure
 Now let's create a simple scatter plot with 100 random points of variying color and size.
@@ -207,4 +259,4 @@ In addition to the `executable` property, the `plotly.io.orca.config` object can
 
 
 ### Saving Configuration Settings
-Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method.  Saved setting will be automatically loaded at the start of future sessions.
+Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method.  Saved setting will be automatically loaded at the start of future sessions.

doc/python/static-image-export.md

@@ -41,31 +41,20 @@ Plotly figures are interactive when viewed in a web browser: you can hover over
 
 
 <!-- #region -->
-#### Install Dependencies
-Static image generation requires the [orca](https://github.com/plotly/orca) commandline utility and the [psutil](https://github.com/giampaolo/psutil) and [requests](https://2.python-requests.org/en/master/) Python libraries. There are 3 general approach to installing these dependencies.
-
-##### conda
-Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command:
+#### Install Dependencies (Kaleido)
+Static image generation requires the [`kaleido`](https://github.com/plotly/Kaleido) package which can be installed using pip...
 ```
-$ conda install -c plotly plotly-orca==1.2.1 psutil requests
+$ pip install -U kaleido
 ```
 
-**Note:** Even if you do not want to use conda to manage your Python dependencies, it is still useful as a cross platform tool for managing native libraries and command-line utilities (e.g. git, wget, graphviz, boost, gcc, nodejs, cairo, etc.).  For this use-case, start with [Miniconda](https://conda.io/miniconda.html) (~60MB) and tell the installer to add itself to your system `PATH`.  Then run `conda install plotly-orca==1.2.1` and the orca executable will be available system wide.
-
-##### npm + pip
-You can use the [npm](https://www.npmjs.com/get-npm) package manager to install `orca` (and its `electron` dependency), and then use pip to install `psutil`:
-
-```
-$ npm install -g electron@1.8.4 orca
-$ pip install psutil requests
+or conda.
 ```
+$ conda install -c conda-forge kaleido
+``` 
 
-##### Standalone Binaries + pip
-If you are unable to install conda or npm, you can install orca as a precompiled binary for your operating system. Follow the instructions in the orca [README](https://github.com/plotly/orca) to install orca and add it to your system `PATH`. Then use pip to install `psutil`.
+#### Install Dependencies (Orca)
+While Kaleido is now the recommended approach, image export can also be supported by the [orca](https://github.com/plotly/orca) command line utility. See the [Orca Management](/python/orca-management/) section for instructions on installing, configuring, and troubleshooting orca.
 
-```
-$ pip install psutil requests
-```
 <!-- #endregion -->
 
 ### Create a Figure
@@ -157,33 +146,6 @@ fig.write_image("images/fig1.eps")
 
 **Note:** It is important to note that any figures containing WebGL traces (i.e. of type `scattergl`, `heatmapgl`, `contourgl`, `scatter3d`, `surface`, `mesh3d`, `scatterpolargl`, `cone`, `streamtube`, `splom`, or `parcoords`) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image.
 
-<!-- #region -->
-### Install orca on Google Colab
-```
-!pip install plotly>=4.7.1
-!wget https://github.com/plotly/orca/releases/download/v1.2.1/orca-1.2.1-x86_64.AppImage -O /usr/local/bin/orca
-!chmod +x /usr/local/bin/orca
-!apt-get install xvfb libgtk2.0-0 libgconf-2-4
-```
-
-Once this is done you can use this code to make, show and export a figure:
-
-```python
-import plotly.graph_objects as go
-fig = go.Figure( go.Scatter(x=[1,2,3], y=[1,3,2] ) )
-fig.write_image("fig1.svg")
-fig.write_image("fig1.png")
-```
-
-The files can then be downloaded with:
-
-```python
-from google.colab import files
-files.download('fig1.svg')
-files.download('fig1.png')
-```
-<!-- #endregion -->
-
 ### Get Image as Bytes
 The `plotly.io.to_image` function is used to return an image as a bytes object. You can also use the `.to_image` graph object figure method.
 
@@ -215,7 +177,45 @@ img_bytes = fig.to_image(format="png", width=600, height=350, scale=2)
 Image(img_bytes)
 ```
 
-### Summary
-In summary, to export high-quality static images from plotly.py, all you need to do is install orca, psutil, and requests and then use the `plotly.io.write_image` and `plotly.io.to_image` functions (or the `.write_image` and `.to_image` graph object figure methods).
+<!-- #region -->
+### Specify Image Export Engine
+If `kaleido` is installed, it will automatically be used to perform image export.  If it is not installed, plotly.py will attempt to use orca instead. The `engine` argument to the `to_image` and `write_image` functions can be used to override this default behavior.
+
+Here is an example of specifying that orca should be used:
+```python
+fig.to_image(format="png", engine="orca")
+```
+
+And, here is an example of specifying that Kaleido should be used:
+```python
+fig.to_image(format="png", engine="kaleido")
+```
+
+<!-- #endregion -->
 
-If you want to know more about how the orca integration works, or if you need to troubleshoot an issue, please check out the [Orca Management](/python/orca-management/) section.
+<!-- #region -->
+### Image Export Settings (Kaleido)
+Various image export settings can be configured using the `plotly.io.kaleido.scope` object. For example, the `default_format` property can be used to specify that the default export format should be `svg` instead of `png`
+
+```python
+import plotly.io as pio
+pio.kaleido.scope.default_format = "svg"
+```  
+
+Here is a complete listing of the available image export settings:
+
+ - **`default_width`**: The default pixel width to use on image export.
+ - **`default_height`**: The default pixel height to use on image export.
+ - **`default_scale`**: The default image scale facor applied on image export.
+ - **`default_format`**: The default image format used on export. One of `"png"`, `"jpeg"`, `"webp"`, `"svg"`, `"pdf"`, or `"eps"`.
+ - **`mathjax`**: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle.
+ - **`topojson`**: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the [Plotly.js topojson files](https://github.com/plotly/plotly.js/tree/master/dist/topojson).
+ - **`mapbox_access_token`**: The default Mapbox access token.
+
+<!-- #endregion -->
+
+### Image Export Settings (Orca)
+See the [Orca Management](/python/orca-management/) section for information on how to specify image export settings when using orca.
+
+### Summary
+In summary, to export high-quality static images from plotly.py, all you need to do is install the `kaleido` package and then use the `plotly.io.write_image` and `plotly.io.to_image` functions (or the `.write_image` and `.to_image` graph object figure methods).