changelog and doc tweaks

zf-z · Jul 15, 2020 · c929086 · c929086
1 parent 4fd8736
commit c929086
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,24 +4,27 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [4.9.0] - unreleased
 
-### Updated
-
-- Updated Plotly.js to version 1.54.6. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.6/CHANGELOG.md) for more information.
-- Added all cartesian-2d Plotly Express functions, plus `imshow` to Pandas backend with `kind` option
-- `plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
--
 ### Added
 
 - Added image export support using [Kaleido](https://github.com/plotly/Kaleido). The image export backend can be configured using the new `engine` argument to `plotly.io.to_image` and `plotly.io.write_image`. The `engine` argument may be set to `"kaleido"`, `"orca"`, or `"auto"`. The default is `engine="auto"`, in which case the Kaleido backend is enabled if the `kaleido` package from PyPI is installed, otherwise Orca is used. ([#2613](https://github.com/plotly/plotly.py/pull/2613)).
-- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
+- `plotly.express.timeline()` added as an official alternative to `plotly.figure_factories.create_gantt()` ([#2626](https://github.com/plotly/plotly.py/pull/2626))
+- `create_hexbin_mapbox()` added to Figure Factories, with thanks to [@RenaudLN](https://github.com/RenaudLN) for the impressive contribution!
 - `facet_row_spacing` and `facet_col_spacing` added to Plotly Express cartesian 2d functions ([#2614](https://github.com/plotly/plotly.py/pull/2614))
-- `base` added to Plotly Express `bar` and `bar_polar` functions
-- `plotly.express.timeline()` added as an official alternative to `plotly.figure_factories.create_gantt()`
--  `create_hexbin_mapbox()` added to Figure Factories, with thanks to [@RenaudLN](https://github.com/RenaudLN) for the contribution!
+- `base` added to Plotly Express `bar` and `bar_polar` functions ([#2626](https://github.com/plotly/plotly.py/pull/2626))
+- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
 
 ### Fixed
 
 - trendline traces are now of type `scattergl` when `render_mode="webgl"` in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
+- regression from 4.8.1 whereby `"parent"` was not accepted as part of `path` for `px.sunburst()` and `px.treemap()` ([#2640](https://github.com/plotly/plotly.py/pull/2640))
+- `create_dendrogram()` figure factory now works correctly with `scipy` 1.5.1 ([#2627](https://github.com/plotly/plotly.py/pull/2627))
+
+### Updated
+
+- Updated Plotly.js to version 1.54.6. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.6/CHANGELOG.md) for more information.
+- Added all cartesian-2d Plotly Express functions, plus `imshow`, to Pandas backend with `kind` option ([#2541](https://github.com/plotly/plotly.py/pull/2541))
+- `plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
+- Javascript extensions are now build using Node 12, and have an updated `package-lock.json` with many fewer security warnings ([#2636](https://github.com/plotly/plotly.py/pull/2636))
 
 
 ## [4.8.2] - 2020-06-26

diff --git a/README.md b/README.md
@@ -133,24 +133,33 @@ jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.
 
 Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.
 
-### Static Image Export with Kaleido
+### Static Image Export
 
-plotly.py supports static image export using the `to_image` and `write_image`
-functions in the `plotly.io` module. This functionality requires the
-[`kaleido`](https://github.com/plotly/Kaleido) package which can be installed
+plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
+using the either the [`kaleido`](https://github.com/plotly/Kaleido)
+package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca)
+command line utility (legacy as of `plotly` version 4.9).
+
+#### Kaleido
+
+The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
 using pip...
 
 ```
 $ pip install -U kaleido
 ```
 
 or conda.
+
 ```
 $ conda install -c plotly python-kaleido
-``` 
+```
 
-### Static Image Export with Orca
-While Kaleido is now the recommended image export approach because it is easier to install and more widely compatible, image export can also be supported
+#### Orca
+
+While Kaleido is now the recommended image export approach because it is easier to install
+and more widely compatible, [static image export](https://plotly.com/python/static-image-export/)
+can also be supported
 by the legacy [orca](https://github.com/plotly/orca) command line utility and the
  [`psutil`](https://github.com/giampaolo/psutil) Python package.
 
@@ -168,13 +177,6 @@ pip install psutil
 
 and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
 
-#### Troubleshooting
-
-##### Wrong Executable found
-
-If you get an error message stating that the `orca` executable that was found is not valid, this may be because another executable with the same name was found on your system. Please specify the complete path to the Plotly-Orca binary that you downloaded (for instance in the Miniconda folder) with the following command:
-
-`plotly.io.orca.config.executable = '/home/your_name/miniconda3/bin/orca'`
 
 ### Extended Geo Support
 

diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md
@@ -180,42 +180,49 @@ Please check out our [Troubleshooting guide](/python/troubleshooting/) if you ru
 
 See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.
 
-#### Static Image Export Support
+### Static Image Export
 
-plotly.py supports static image export using the `to_image` and `write_image`
-functions in the `plotly.io` package. This functionality requires the
-installation of the plotly [orca](https://github.com/plotly/orca) command line utility and the
-[`psutil`](https://github.com/giampaolo/psutil) and [`requests`](https://2.python-requests.org/en/master/) Python packages.
+plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
+using the either the [`kaleido`](https://github.com/plotly/Kaleido)
+package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca)
+command line utility (legacy as of `plotly` version 4.9).
 
-> Note: The `requests` library is used to communicate between the Python process and a local orca server process, it is not used to communicate with any external services.
+#### Kaleido
 
-These dependencies can all be installed using conda:
+The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
+using pip...
 
 ```
-$ conda install -c plotly plotly-orca==1.2.1 psutil requests
+$ pip install -U kaleido
 ```
 
-Or, `psutil` and `requests` can be installed using pip...
+or conda.
 
 ```
-$ pip install psutil requests
+$ conda install -c plotly python-kaleido
 ```
 
-and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
+#### Orca
 
-These packages contain everything you need to save figures as static images.
+While Kaleido is now the recommended image export approach because it is easier to install
+and more widely compatible, [static image export](https://plotly.com/python/static-image-export/)
+can also be supported
+by the legacy [orca](https://github.com/plotly/orca) command line utility and the
+ [`psutil`](https://github.com/giampaolo/psutil) Python package.
 
-<!-- #endregion -->
+These dependencies can both be installed using conda:
 
-```python
-import plotly.graph_objects as go
-fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
-fig.write_image('figure.png')
+```
+conda install -c plotly plotly-orca==1.3.1 psutil
 ```
 
-<!-- #region -->
+Or, `psutil` can be installed using pip...
+
+```
+pip install psutil
+```
 
-See [_Static Image Export in Python_](/python/static-image-export/) for more information on static image export.
+and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
 
 #### Extended Geo Support
 

diff --git a/doc/python/orca-management.md b/doc/python/orca-management.md
@@ -36,7 +36,7 @@ jupyter:
 ### Overview
 This section covers the lower-level details of how plotly.py can use orca to perform static image generation.
 
-> Orca is no longer the recommended way to do static image export.  We now recommend Kaleido, as described in the [Static Image Export](/python/static-image-export/) section .
+> As of `plotly` version 4.9, Orca is no longer the recommended way to do static image export.  We now recommend Kaleido, as described in the [Static Image Export](/python/static-image-export/) section .
 
 Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
 

diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md
@@ -42,21 +42,23 @@ Plotly figures are interactive when viewed in a web browser: you can hover over
 
 <!-- #region -->
 #### Install Dependencies
-Static image generation requires either [Kaleido](https://github.com/plotly/Kaleido) (recommended) or [orca](https://github.com/plotly/orca) (legacy). The `kaleido` package can be installed using pip...
+
+Static image generation requires either [Kaleido](https://github.com/plotly/Kaleido) (recommended, supported as of `plotly` 4.9) or [orca](https://github.com/plotly/orca) (legacy as of `plotly` 4.9). The `kaleido` package can be installed using pip...
 ```
 $ pip install -U kaleido
 ```
 
 or conda.
 ```
 $ conda install -c plotly python-kaleido
-``` 
+```
 
 While Kaleido is now the recommended approach, image export can also be supported by the legacy [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.
 
 <!-- #endregion -->
 
 ### Create a Figure
+
 Now let's create a simple scatter plot with 100 random points of varying color and size.
 
 ```python
@@ -87,6 +89,7 @@ fig.show()
 ```
 
 ### Write Image File
+
 The `plotly.io.write_image` function is used to write an image to a file or file-like python object.  You can also use the `.write_image` graph object figure method.
 
 Let's first create an output directory to store our images
@@ -146,6 +149,7 @@ 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.
 
 ### 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.
 
 Let convert the figure to a **PNG** bytes object...
@@ -178,7 +182,7 @@ Image(img_bytes)
 
 <!-- #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.
+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
@@ -199,7 +203,7 @@ Various image export settings can be configured using the `plotly.io.kaleido.sco
 ```python
 import plotly.io as pio
 pio.kaleido.scope.default_format = "svg"
-```  
+```
 
 Here is a complete listing of the available image export settings:
 

diff --git a/doc/python/troubleshooting.md b/doc/python/troubleshooting.md
@@ -102,4 +102,14 @@ unset NODE_OPTIONS
 set NODE_OPTIONS=
 ```
 
-<!-- #endregion -->
+<!-- #endregion -->
+
+
+### Orca Problems
+
+> Note: as of `plotly` version 4.9, we recommend using [`kaleido`](https://github.com/plotly/Kaleido)
+> instead of Orca for [static image export](/python/static-image-export/)
+
+If you get an error message stating that the `orca` executable that was found is not valid, this may be because another executable with the same name was found on your system. Please specify the complete path to the Plotly-Orca binary that you downloaded (for instance in the Miniconda folder) with the following command:
+
+`plotly.io.orca.config.executable = '/home/your_name/miniconda3/bin/orca'`