From e8a80feacdf3efab73e74b91a775682f22443238 Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Fri, 21 Jul 2023 15:24:57 -0400
Subject: [PATCH 01/12] reapply fixes from #4221, #3531, and #4231 - thanks
 @tanmaychimurkar, @Nicolas-Reyland, and @jegrami

---
 doc/python/animations.md              | 2 +-
 doc/python/interactive-html-export.md | 2 +-
 doc/python/legend.md                  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/python/animations.md b/doc/python/animations.md
index ffd948c7064..c765d36621f 100644
--- a/doc/python/animations.md
+++ b/doc/python/animations.md
@@ -37,7 +37,7 @@ jupyter:
 
 Several [Plotly Express](/python/plotly-express/)  functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
 
-Here is an example of an animated scatter plot creating using Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation.
+Here is an example of an animated scatter plot created with Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation.
 
 ```python
 import plotly.express as px
diff --git a/doc/python/interactive-html-export.md b/doc/python/interactive-html-export.md
index 9691e0f2398..bd7284beb02 100644
--- a/doc/python/interactive-html-export.md
+++ b/doc/python/interactive-html-export.md
@@ -46,7 +46,7 @@ Any figure can be saved as an HTML file using the `write_html` method. These HTM
 ```python
 import plotly.express as px
 
-fig =px.scatter(x=range(10), y=range(10))
+fig = px.scatter(x=range(10), y=range(10))
 fig.write_html("path/to/file.html")
 ```
 <!-- #endregion -->
diff --git a/doc/python/legend.md b/doc/python/legend.md
index 9ca47748be1..b699ae8c557 100644
--- a/doc/python/legend.md
+++ b/doc/python/legend.md
@@ -193,7 +193,7 @@ fig.show()
 
 *New in 5.11*
 
-Set the width of horizontal legend entries by setting `entrywidth`. Here we set it to `70` pixels. Pixels is the default unit for `entrywidth`, but you can set it to be a fraction of the plot width using `entrywidthmode='fraction`.
+Set the width of horizontal legend entries by setting `entrywidth`. Here we set it to `70` pixels. Pixels is the default unit for `entrywidth`, but you can set it to be a fraction of the plot width using `entrywidthmode='fraction'`.
 
 ```python
 import plotly.express as px

From dd3187f4b73258ae26775a7dbdc64295ff1b3a8a Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Fri, 21 Jul 2023 16:14:13 -0400
Subject: [PATCH 02/12] Update px-arguments.md

---
 doc/python/px-arguments.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/doc/python/px-arguments.md b/doc/python/px-arguments.md
index 223d6dac9dc..8987c49f2f0 100644
--- a/doc/python/px-arguments.md
+++ b/doc/python/px-arguments.md
@@ -35,7 +35,7 @@ jupyter:
 
 ### Plotly Express works with Column-oriented, Matrix or Geographic Data
 
-[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which operates on a variety of types of data and produces [easy-to-style figures](/python/styling-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/).
 
 Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a `DataFrame` (in either "long" or "wide" format, see below). These functions use Pandas internally to process the data, but also accept other types of DataFrames as arguments. See the **Input Data as Non-Pandas DataFrames** section below for more details.
 
@@ -170,14 +170,12 @@ fig.show()
 
 ### Input Data as Non-Pandas `DataFrame`s
 
-**New in 5.16**
+**New in 5.15**
 
-In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method or supports the [Python dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), for example, a [Polars](https://www.pola.rs/) DataFrame.
+In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method, for example, a [Polars](https://www.pola.rs/) DataFrame.
 
 Plotly Express uses Pandas internally to process the data. When you provide a Non-Pandas DataFrame to the `data_frame` argument of a Plotly Express function, the entire DataFrame is converted to a Pandas DataFrame.
 
-If you are using a type of DataFrame that doesn't have a `to_pandas` method, but supports the Python dataframe interchange protocol, you'll need to have Pandas version 2.0.3 or later installed. 
-
 In this example, we use a Polars DataFrame. If you are using Polars, you'll need to install `pyarrow`, which is used by its [`to_pandas` method](
 https://pola-rs.github.io/polars/py-polars/html/reference/dataframe/api/polars.DataFrame.to_pandas.html)
 

From 3c9bee28528eab43cf812e789af9eb756a97212a Mon Sep 17 00:00:00 2001
From: AtharvaKatre <45846529+AtharvaKatre@users.noreply.github.com>
Date: Thu, 13 Jul 2023 11:32:03 +0530
Subject: [PATCH 03/12] Update treemaps.md

Fixed typo
---
 doc/python/treemaps.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/python/treemaps.md b/doc/python/treemaps.md
index b86636e01df..98fbeadcd40 100644
--- a/doc/python/treemaps.md
+++ b/doc/python/treemaps.md
@@ -186,7 +186,7 @@ This example uses the following attributes:
 1.  [values](https://plotly.com/python/reference/treemap/#treemap-values): sets the values associated with each of the sectors.
 2.  [textinfo](https://plotly.com/python/reference/treemap/#treemap-textinfo): determines which trace information appear on the graph that can be 'text', 'value', 'current path', 'percent root', 'percent entry', and 'percent parent', or any combination of them.
 3.  [pathbar](https://plotly.com/python/reference/treemap/#treemap-pathbar): a main extra feature of treemap to display the current path of the visible portion of the hierarchical map. It may also be useful for zooming out of the graph.
-4.  [branchvalues](https://plotly.com/python/reference/treemap/#treemap-branchvalues): determines how the items in `values` are summed. When set to "total", items in `values` are taken to be value of all its descendants. In the example below Eva = 65, which is equal to 14 + 12 + 10 + 2 + 6 + 6 + 1 + 4.
+4.  [branchvalues](https://plotly.com/python/reference/treemap/#treemap-branchvalues): determines how the items in `values` are summed. When set to "total", items in `values` are taken to be value of all its descendants. In the example below Eve = 65, which is equal to 14 + 12 + 10 + 2 + 6 + 6 + 1 + 4.
     When set to "remainder", items in `values` corresponding to the root and the branches sectors are taken to be the extra part not part of the sum of the values at their leaves.
 
 ```python

From f1343135551980a59144d5e90d3e51a92bdfb115 Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Tue, 11 Jul 2023 11:50:03 -0400
Subject: [PATCH 04/12] Update map-configuration.md

---
 doc/python/map-configuration.md | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/doc/python/map-configuration.md b/doc/python/map-configuration.md
index 5a2f5a349f6..6e9f54e4d7e 100644
--- a/doc/python/map-configuration.md
+++ b/doc/python/map-configuration.md
@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.3.1
+      format_version: '1.3'
+      jupytext_version: 1.14.7
   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.6.8
+    version: 3.10.4
   plotly:
     description: How to configure and style base maps for Choropleths and Bubble Maps.
     display_as: maps
@@ -119,9 +119,7 @@ fig.show()
 
 ### Map Projections
 
-Geo maps are drawn according to a given map [projection](https://en.wikipedia.org/wiki/Map_projection) that flattens the Earth's roughly-spherical surface into a 2-dimensional space.
-
-The available projections are `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, `'albers usa'`, `'winkel tripel'`, `'aitoff'` and `'sinusoidal'`.
+Geo maps are drawn according to a given map [projection](https://en.wikipedia.org/wiki/Map_projection) that flattens the Earth's roughly-spherical surface into a 2-dimensional space. In the following examples, we show the `'orthographic'` and `'natural earth'` projections, two of the many projection types available. For a full list of available projection types, see the [layout.geo reference documentation](https://plotly.com/python/reference/layout/geo/#layout-geo-projection-type).
 
 ```python
 import plotly.graph_objects as go
@@ -221,7 +219,3 @@ fig.show()
 ### Reference
 
 See https://plotly.com/python/reference/layout/geo/ for more information and chart attribute options!
-
-```python
-
-```
\ No newline at end of file

From a62d8e117f8b2ff65e986d84acf16bb9ec8f6a93 Mon Sep 17 00:00:00 2001
From: Ryan Folks <47860863+RyanDoesMath@users.noreply.github.com>
Date: Mon, 22 May 2023 09:22:58 -0400
Subject: [PATCH 05/12] Fixed a typo in figure-factory-subplots.md

Fixed the world's smallest typo in the doc file for figure factory.
---
 doc/python/figure-factory-subplots.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/python/figure-factory-subplots.md b/doc/python/figure-factory-subplots.md
index eaaa55b797a..3a6c837692d 100644
--- a/doc/python/figure-factory-subplots.md
+++ b/doc/python/figure-factory-subplots.md
@@ -61,7 +61,7 @@ Y, X = np.meshgrid(x, y)
 u = -1 - X**2 + Y
 v = 1 + X - Y**2
 
-fig2 = ff.create_streamline(x, y, u, v, arrow_scale=.1, name='Steamline')
+fig2 = ff.create_streamline(x, y, u, v, arrow_scale=.1, name='Streamline')
 ```
 
 Edit the figures' x and y axes attributes to create subplots:

From c2f25844234ab3ccfd1540b28ff7b90084174e56 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20DIDIER?=
 <73602526+sdidier-dev@users.noreply.github.com>
Date: Sat, 20 Aug 2022 20:56:58 +0200
Subject: [PATCH 06/12] Improve syntax and consistency

---
 doc/python/configuration-options.md | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/doc/python/configuration-options.md b/doc/python/configuration-options.md
index f0590762fef..52dcc8764ec 100644
--- a/doc/python/configuration-options.md
+++ b/doc/python/configuration-options.md
@@ -53,7 +53,7 @@ import plotly.graph_objects as go
 
 fig = go.Figure()
 
-config = dict({'scrollZoom': True})
+config = {'scrollZoom': True}
 
 fig.add_trace(
     go.Scatter(
@@ -244,6 +244,8 @@ fig.add_trace(
         y=[1, 3, 1]))
 
 fig.update_layout(modebar_remove=['zoom', 'pan'])
+
+fig.show()
 ```
 
 ### Add optional shape-drawing buttons to modebar
@@ -253,16 +255,19 @@ fig.update_layout(modebar_remove=['zoom', 'pan'])
 Some modebar buttons of Cartesian plots are optional and have to be added explicitly, using the `modeBarButtonsToAdd` config attribute. These buttons are used for drawing or erasing shapes. See [the tutorial on shapes and shape drawing](python/shapes#drawing-shapes-on-cartesian-plots) for more details.
 
 ```python
-import plotly.graph_objects as go
 import plotly.express as px
+
 df = px.data.iris()
+
 fig = px.scatter(df, x='petal_width', y='sepal_length', color='species')
+
 fig.update_layout(
     dragmode='drawopenpath',
     newshape_line_color='cyan',
     title_text='Draw a path to separate versicolor and virginica'
 )
-fig.show(config={'modeBarButtonsToAdd':['drawline',
+
+fig.show(config={'modeBarButtonsToAdd': ['drawline',
                                         'drawopenpath',
                                         'drawclosedpath',
                                         'drawcircle',
@@ -276,10 +281,12 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
 The `layout.modebar.add` attribute can be used instead of the approach used above:
 
 ```python
-import plotly.graph_objects as go
 import plotly.express as px
+
 df = px.data.iris()
+
 fig = px.scatter(df, x='petal_width', y='sepal_length', color='species')
+
 fig.update_layout(
     dragmode='drawopenpath',
     newshape_line_color='cyan',
@@ -292,6 +299,8 @@ fig.update_layout(
         'eraseshape'
        ]
 )
+
+fig.show()
 ```
 
 ### Double-Click Delay
@@ -304,12 +313,12 @@ import plotly.graph_objects as go
 config = {'doubleClickDelay': 1000}
 
 fig = go.Figure(go.Bar(
-    y = [3, 5, 3, 2],
-    x = ["2019-09-02", "2019-10-10", "2019-11-12", "2019-12-22"],
-    texttemplate = "%{label}",
-    textposition = "inside"))
+    y=[3, 5, 3, 2],
+    x=["2019-09-02", "2019-10-10", "2019-11-12", "2019-12-22"],
+    texttemplate="%{label}",
+    textposition="inside"))
 
-fig.update_layout(xaxis = {'type': 'date'})
+fig.update_layout(xaxis={'type': 'date'})
 
 fig.show(config=config)
 ```
@@ -320,4 +329,4 @@ The same configuration dictionary that you pass to the `config` parameter of the
 
 #### Reference
 
-See config options at https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js#L6
+See config options at https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js

From 7120002a73c185cd6ab5c4144367372d91feeaf2 Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Tue, 16 Aug 2022 17:18:48 -0400
Subject: [PATCH 07/12] Update what_about_dash.md

---
 doc/what_about_dash.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/doc/what_about_dash.md b/doc/what_about_dash.md
index bef6ac916dd..696aa93a632 100644
--- a/doc/what_about_dash.md
+++ b/doc/what_about_dash.md
@@ -15,11 +15,9 @@ fig = go.Figure() # or any Plotly Express function e.g. px.bar(...)
 # fig.add_trace( ... )
 # fig.update_layout( ... )
 
-import dash
-import dash_core_components as dcc
-import dash_html_components as html
+from dash import Dash, dcc, html
 
-app = dash.Dash()
+app = Dash()
 app.layout = html.Div([
     dcc.Graph(figure=fig)
 ])

From 85de744b407b92ecee3bf6f3632a8f7260aa6525 Mon Sep 17 00:00:00 2001
From: Farzin Ghanbari <tfarzin@gmail.com>
Date: Tue, 12 Oct 2021 12:43:14 +0330
Subject: [PATCH 08/12] Update 3d-scatter-plots.md

---
 doc/python/3d-scatter-plots.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/python/3d-scatter-plots.md b/doc/python/3d-scatter-plots.md
index 12b2de61f67..46e389b5654 100644
--- a/doc/python/3d-scatter-plots.md
+++ b/doc/python/3d-scatter-plots.md
@@ -70,6 +70,7 @@ fig = px.scatter_3d(df, x='sepal_length', y='sepal_width', z='petal_width',
 
 # tight layout
 fig.update_layout(margin=dict(l=0, r=0, b=0, t=0))
+fig.show()
 ```
 
 #### 3d scatter plots in Dash

From de7e5c0ab616628ccc60314dd08ab12c42af8e06 Mon Sep 17 00:00:00 2001
From: shaido987 <shaido987@hotmail.com>
Date: Thu, 9 Sep 2021 16:34:08 +0800
Subject: [PATCH 09/12] Fix typo in marker-style.md

Diamond is mentioned twice in the basic symbol list.
---
 doc/python/marker-style.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/python/marker-style.md b/doc/python/marker-style.md
index 128b22d04c5..21b0a2ac052 100644
--- a/doc/python/marker-style.md
+++ b/doc/python/marker-style.md
@@ -326,7 +326,7 @@ fig.show()
 
 The `marker_symbol` attribute allows you to choose from a wide array of symbols to represent markers in your figures.
 
-The basic symbols are: `circle`, `square`, `diamond`, `cross`, `x`, `triangle`, `pentagon`, `hexagram`, `star`, `diamond`, `hourglass`, `bowtie`, `asterisk`, `hash`, `y`, and `line`.
+The basic symbols are: `circle`, `square`, `diamond`, `cross`, `x`, `triangle`, `pentagon`, `hexagram`, `star`, `hourglass`, `bowtie`, `asterisk`, `hash`, `y`, and `line`.
 
 Each basic symbol is also represented by a number. Adding 100 to that number is equivalent to appending the suffix "-open" to a symbol name. Adding 200 is equivalent to appending "-dot" to a symbol name. Adding 300 is equivalent to appending "-open-dot" or "dot-open" to a symbol name.
 

From 4e4fa6e9c0cb5cf9ab4a30fbb108526e469f1549 Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Mon, 24 Jul 2023 10:04:30 -0400
Subject: [PATCH 10/12] Update colorscales.md

---
 doc/python/colorscales.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/python/colorscales.md b/doc/python/colorscales.md
index fe2ac574227..ea94f1cf7e1 100644
--- a/doc/python/colorscales.md
+++ b/doc/python/colorscales.md
@@ -307,11 +307,11 @@ Using `labelalias` you can replace some labels on the `colorbar` with alternativ
 ```python
 import plotly.graph_objects as go
 
-import urllib
+import urllib.request as request
 import json
 
 # Load heatmap data
-response = urllib.request.urlopen(
+response = request.urlopen(
     "https://raw.githubusercontent.com/plotly/datasets/master/custom_heatmap_colorscale.json")
 dataset = json.load(response)
 

From 7a28a58036d2ddfeaaff287358f3ccabfdcb07b2 Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Mon, 24 Jul 2023 10:06:37 -0400
Subject: [PATCH 11/12] Update legend.md

---
 doc/python/legend.md | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/doc/python/legend.md b/doc/python/legend.md
index b699ae8c557..02e8a8fff5d 100644
--- a/doc/python/legend.md
+++ b/doc/python/legend.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.5
+      jupytext_version: 1.14.6
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -580,7 +580,7 @@ fig.show()
 
 By default, all traces appear on one legend. To have multiple legends, specify an alternative legend for a trace using the `legend` property. For a second legend, set `legend="legend2"`. Specify more legends with `legend="legend3"`, `legend="legend4"` and so on.
 
-In this example, the last two scatter traces display on the second legend, "legend2". On the figure's layout, we then position and style this legend to display on the right of the graph below the first legend.
+In this example, the last two scatter traces display on the second legend, "legend2". On the figure's layout, we then position and style each legend.
 
 
 ```python
@@ -622,20 +622,25 @@ fig = go.Figure(
     ],
     layout=dict(
         title="GDP Per Capita",
-        legend={"title": "By country", "bgcolor": "Orange",},
+        legend={
+            "title": "By country",
+            "xref": "container",
+            "yref": "container",
+            "y": 0.65,
+            "bgcolor": "Orange",
+        },
         legend2={
-            "x": 1.155,
-            "y": 0.55,
-            "xanchor": "right",
-            "yanchor": "middle",
+            "title": "By continent",
+            "xref": "container",
+            "yref": "container",
+            "y": 0.85,
             "bgcolor": "Gold",
-            "title": {"text": "By continent"},
+
         },
     ),
 )
 
 fig.show()
-
 ```
 
 ### Positioning Legends
@@ -666,7 +671,6 @@ fig = go.Figure(
             "xref": "container",
             "yref": "container",
             "bgcolor": "Gold",
-            "title": {"text": "By continent"},
         },
     ),
 )

From 0ae75963e3871513f1f51fcf0cf6e622993b061d Mon Sep 17 00:00:00 2001
From: Liam Connors <liam@plot.ly>
Date: Mon, 24 Jul 2023 10:06:40 -0400
Subject: [PATCH 12/12] Update shapes.md

---
 doc/python/shapes.md | 69 ++++++++++++++++++++++++++++++--------------
 1 file changed, 48 insertions(+), 21 deletions(-)

diff --git a/doc/python/shapes.md b/doc/python/shapes.md
index f44c6050c48..ce131bc39c4 100644
--- a/doc/python/shapes.md
+++ b/doc/python/shapes.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.5
+      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.8
+    version: 3.10.10
   plotly:
     description: How to make SVG shapes in python. Examples of lines, circle, rectangle,
       and path.
@@ -677,12 +677,12 @@ import plotly.graph_objects as go
 fig = go.Figure()
 
 fig.add_shape(
-    type="rect", 
-    fillcolor='turquoise', 
-    x0=1, 
-    y0=1, 
-    x1=2, 
-    y1=3, 
+    type="rect",
+    fillcolor='turquoise',
+    x0=1,
+    y0=1,
+    x1=2,
+    y1=3,
     label=dict(text="Text in rectangle")
 )
 fig.add_shape(
@@ -701,8 +701,8 @@ fig.show()
 
 #### Styling Text Labels
 
-Use the `font` property to configure the `color`, `size`, and `family` of the label font. 
-In this example, we change the label color of the first rectangle to "DarkOrange", set the size of the text above the line to 20, and change the font family and set the font size on the second rectangle. 
+Use the `font` property to configure the `color`, `size`, and `family` of the label font.
+In this example, we change the label color of the first rectangle to "DarkOrange", set the size of the text above the line to 20, and change the font family and set the font size on the second rectangle.
 
 ```python
 import plotly.graph_objects as go
@@ -776,7 +776,7 @@ fig.add_shape(
 
 fig.add_shape(
     type="line",
-    line_color="MediumSlateBlue",    
+    line_color="MediumSlateBlue",
     x0=3,
     y0=2,
     x1=5,
@@ -870,10 +870,10 @@ fig.show()
 
 #### Setting Label Anchors
 
-`xanchor` sets a label's horizontal positional anchor and `yanchor` sets its vertical position anchor. 
+`xanchor` sets a label's horizontal positional anchor and `yanchor` sets its vertical position anchor.
 Use `xanchor` to bind the `textposition` to the "left", "center" or "right" of the label text and `yanchor` to bind `textposition` to the "top", "middle" or "bottom" of the label text.
 
-In this example, `yanchor`is set to "top", instead of the default of "bottom" for lines, meaning the text displays below the line. 
+In this example, `yanchor`is set to "top", instead of the default of "bottom" for lines, meaning the text displays below the line.
 
 
 ```python
@@ -917,18 +917,27 @@ fig.show()
 
 *New in 5.15*
 
-Use `texttemplate` to add text with variables to shapes. `texttemplate` uses d3 number and date formatting and supports raw variables, which use the raw data from the shape definition, and some calculated variables. Add a variable with "%{variable}".
+Use `texttemplate` to add text with variables to shapes. You have access to raw variables (`x0`, `x1`, `y0`, `y1`), which use raw data values from the shape definition, and the following calculated variables:
 
-This example adds the raw variables `x0` and `y0` to a rectangle and shows the calculated variables `height`, `slope`, and `width` on three other shapes. 
+- `xcenter`: (x0 + x1) / 2
+- `ycenter`: (y0 + y1) / 2
+- `dx`: x1 - x0
+- `dy`: y1 - y0
+- `width`: abs(x1 - x0)
+- `height`: abs(y1 - y0)
+- `length` (for lines only): sqrt(dx^2 + dy^2)
+- `slope`: (y1 - y0) / (x1 - x0)
 
-For a complete list of available variables, see the [Shape Reference Docs](https://plotly.com/python/reference/layout/shapes/).
+`texttemplate` supports d3 number and date formatting.
 
+Add a variable with "%{variable}". This example adds the raw variables `x0` and `y0` to a rectangle and shows the calculated variables `height`, `slope`, `length`, and `width` on three other shapes.
 
 ```python
 import plotly.graph_objects as go
 
 fig = go.Figure()
 
+
 fig.add_shape(
     type="rect",
     fillcolor="MediumSlateBlue",
@@ -955,9 +964,12 @@ fig.add_shape(
     x0=3,
     y0=0.5,
     x1=5,
-    y1=0.8,
+    y1=1.5,
     line_width=3,
-    label=dict(texttemplate="Slope: %{slope:.3f}", font=dict(size=20)),
+    label=dict(
+        texttemplate="Slope of %{slope:.3f} and length of %{length:.3f}",
+        font=dict(size=20),
+    ),
 )
 fig.add_shape(
     type="rect",
@@ -980,15 +992,31 @@ fig.show()
 
 *New in 5.15*
 
-Use `texttemplate` to add text with variables to new shapes drawn on the graph. This example figure is configured to allow the user to draw lines and automatically labels each line with its slope. Select **Draw line** in the modebar to try it out.
+You can also use `texttemplate` to add text with variables to new shapes drawn on the graph.
+
+In this example, we enable drawing lines on the figure by adding `drawline` to `modeBarButtonsToAdd` in `config`. We then define a `texttemplate` for shapes that shows the calculated variable `dy`. Select **Draw line** in the modebar to try it out.
 
 ```python
 import plotly.graph_objects as go
+from plotly import data
+
+df = data.stocks()
 
 fig = go.Figure(
-    layout=go.Layout(newshape=dict(label=dict(texttemplate="Slope: %{slope:.3f}")))
+    data=go.Scatter(
+        x=df.date,
+        y=df.GOOG,
+    ),
+    layout=go.Layout(
+        yaxis=dict(title="Price in USD"),
+        newshape=dict(
+            label=dict(texttemplate="Change: %{dy:.2f}")
+        ),
+        title="Google Share Price 2018/2019",
+    ),
 )
 
+
 fig.show(
     config={
         "modeBarButtonsToAdd": [
@@ -996,7 +1024,6 @@ fig.show(
         ]
     }
 )
-
 ```
 
 ### Reference