Update shapes.md

Author: LiamConnors

doc/python/shapes.md

@@ -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
@@ -930,7 +930,7 @@ Use `texttemplate` to add text with variables to shapes. You have access to raw
 
 `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. 
+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
@@ -1017,6 +1017,85 @@ fig = go.Figure(
 )
 
 
+fig.show(
+    config={
+        "modeBarButtonsToAdd": [
+            "drawline",
+        ]
+    }
+)
+```
+
+#### Shapes in the Legend
+
+*New in 5.16*
+
+You can add a shape to the legend by setting `showlegend=True` on the shape. In this example, we add the second shape to the legend. The name that appears for the shape in the legend is the shape's `name` if it is provided. If no `name` is provided, the shape label's `text` is used. If neither is provided, the legend item appears as "shape \<shape number>". For example, "shape 1".
+
+```python
+import plotly.express as px
+
+df = px.data.stocks(indexed=True)
+
+fig = px.line(df)
+
+fig.add_shape(
+    type="rect",
+    x0="2018-09-24",
+    y0=0,
+    x1="2018-12-18",
+    y1=3,
+    line_width=0,
+    label=dict(text="Decline", textposition="top center", font=dict(size=20)),
+    fillcolor="green",
+    opacity=0.25,
+)
+
+fig.add_shape(
+    showlegend=True,
+    type="line",
+    x0=min(df.index),
+    y0=1,
+    x1=max(df.index),
+    y1=1,
+    line_width=3,
+    line_dash="dot",
+    label=dict(
+        text="Jan 1 2018 Baseline",
+        textposition="end",
+        font=dict(size=20, color="blue"),
+        yanchor="top",
+    ),
+)
+
+fig.show()
+```
+
+`newshape` also supports `showlegend`. In this example, each new line drawn on the graph appears in the legend.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.stocks()
+
+fig = go.Figure(
+    data=go.Scatter(
+        x=df.date,
+        y=df.AAPL,
+        name="Apple"
+    ),
+    layout=go.Layout(
+        yaxis=dict(title="Price in USD"),
+        newshape=dict(
+            showlegend=True,
+            label=dict(texttemplate="Change: %{dy:.2f}")
+        ),
+        title="Apple Share Price 2018/2019",
+    ),
+)
+
+
 fig.show(
     config={
         "modeBarButtonsToAdd": [