Merge pull request #4293 from plotly/docs-update-2

Add back docs changes

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

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)
 

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

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:

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"},
         },
     ),
 )

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
-
-```

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.
 

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,23 +992,38 @@ 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": [
             "drawline",
         ]
     }
 )
-
 ```
 
 ### Reference

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