more shape/text doc cleanup

Author: nicolaskruchten

doc/python/horizontal-vertical-shapes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.0
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
   plotly:
     description: How to add annotated horizontal and vertical lines in Python.
     display_as: file_settings
@@ -32,11 +32,11 @@ jupyter:
     thumbnail: thumbnail/shape.jpg
 ---
 
-### Horizontal and Vertical Lines and Rectangles (Autoshapes)
+### Horizontal and Vertical Lines and Rectangles
 
 *introduced in plotly 4.12*
 
-Horizontal and vertical lines and rectangles (autoshapes) that span an entire
+Horizontal and vertical lines and rectangles that span an entire
 plot can be added via the `add_hline`, `add_vline`, `add_hrect`, and `add_vrect`
 methods of `plotly.graph_objects.Figure`. Shapes added with these methods are
 added as [layout shapes](/python/shapes) (as shown when doing `print(fig)`, for
@@ -45,77 +45,85 @@ range of the plot, and fixed to data coordinates on the other axis. The
 following shows some possibilities, try panning and zooming the resulting figure
 to see how the shapes stick to some axes:
 
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="petal_length", y="petal_width")
+fig.add_hline(y=0.9)
+fig.add_vrect(x0=0.9, x1=2)
+fig.show()
+```
+
+These shapes can be styled by passing the same arguments as are accepted by `add_shape`:
 
 ```python
 import plotly.express as px
 
 df = px.data.iris()
-fig = px.scatter(df, x="sepal_length", y="sepal_width")
-
-# Add a vertical line that spans the entire y axis
-# intersecting the x axis at x=5
-fig.add_vline(x=5, line_color="red")
-# Add a horizontal line that spans the entire x axis
-# intersecting the y axis at y=3
-fig.add_hline(y=3, line_color="blue")
-# Add a vertical rectangle that spans the entire y axis
-# intersecting the x axis at 5.5 and 6.5
-fig.add_vrect(x0=5.5, x1=6.5, line_color="purple")
-# Add a horizontal rectangle that spans the entire x axis
-# intersecting the y axis at 2.5 and 4
-fig.add_hrect(y0=2.5, y1=4, line_color="orange")
-# (try panning and zooming the plot)
+fig = px.scatter(df, x="petal_length", y="petal_width")
+fig.add_vline(x=2.5, line_width=3, line_dash="dash", line_color="green")
+fig.add_hrect(y0=0.9, y1=2.6, line_width=0, fillcolor="red", opacity=0.2)
+fig.show()
+```
+
+#### Adding Text Annotations
+
+[Text annotations](/python/text-and-annotations) can optionally be added to an autoshape
+using the `annotation_text` keyword argument, and positioned using the `annotation_position` argument:
+
+```python
+import plotly.express as px
+
+df = px.data.stocks(indexed=True)
+fig = px.line(df)
+fig.add_hline(y=1, line_dash="dot",
+              annotation_text="Jan 1, 2018 baseline", 
+              annotation_position="bottom right")
+fig.add_vrect(x0="2018-09-24", x1="2018-12-18", 
+              annotation_text="decline", annotation_position="top left",
+              fillcolor="green", opacity=0.25, line_width=0)
 fig.show()
 ```
 
-#### Adding Autoshapes to Multiple Facets / Subplots
+Extra formatting of the annotation can be done using magic-underscores prefixed by `annotation_` or by passing a `dict` or `go.layout.Annotation` instance to the `annotation` argument:
 
-The same line or box can be added to multiple facets by using the `'all'`
-keyword in the `row` and `col` arguments like with `Figure.add_shape`. For
-example
 ```python
 import plotly.express as px
 
-df = px.data.tips()
-fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex")
-# Adds a vertical line to all facets
-fig.add_vline(x=30, row="all", col="all", line_color="purple")
-# Adds a horizontal line to all the rows of the second column
-fig.add_hline(y=6, row="all", col=2, line_color="yellow")
-# Adds a vertical rectangle to all the columns of the first row
-fig.add_vrect(x0=20, x1=40, row=1, col="all", line_color="green")
+df = px.data.stocks(indexed=True)
+fig = px.line(df)
+fig.add_hline(y=1, line_dash="dot",
+              annotation_text="Jan 1, 2018 baseline", 
+              annotation_position="bottom right",
+              annotation_font_size=20,
+              annotation_font_color="blue"
+             )
+fig.add_vrect(x0="2018-09-24", x1="2018-12-18", 
+              annotation_text="decline", annotation_position="top left",
+              annotation=dict(font_size=20, font_family="Times New Roman"),
+              fillcolor="green", opacity=0.25, line_width=0)
 fig.show()
 ```
-The default `row` and `col` values are `"all"` so
-`fig.add_vline(x=30, line_color="purple")` is equivalent
-to `fig.add_vline(x=30, row="all", col="all", line_color="purple")` in the above
-example.
 
-#### Adding Text Annotations to Autoshapes
+#### Adding to Multiple Facets / Subplots
 
-Text [annotations](/python/text-and-annotations) can be added to an autoshape
-using the `annotation` keyword. Using the above example:
+The same line or box can be added to multiple [subplots](/python/subplots/) or [facets](/python/facet-plots/) by setting the `row` and/or `col` to `"all"`. The default `row` and `col` values are `"all"`.
 ```python
 import plotly.express as px
-import plotly.graph_objects as go
-
-df = px.data.tips()
-fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex")
-# Add annotations anchored to the top right corner of the resulting lines
-fig.add_vline(x=30, line_color="purple", annotation=go.layout.Annotation(text="A"))
-# Another way to add annotations when we are only interested in specifying text
-fig.add_hline(y=6, row="all", col=2, line_color="yellow", annotation_text="B")
-# Specify the position of the resulting annotations
-fig.add_vrect(
-    x0=20,
-    x1=40,
-    row=1,
-    col="all",
-    line_color="green",
-    annotation_text="C",
-    annotation_position="bottom inside left",
-)
+
+df = px.data.stocks(indexed=True)
+fig = px.line(df, facet_col="company", facet_col_wrap=2)
+fig.add_hline(y=1, line_dash="dot", row=3, col="all",
+              annotation_text="Jan 1, 2018 baseline", 
+              annotation_position="bottom right")
+fig.add_vrect(x0="2018-09-24", x1="2018-12-18", row="all", col=1,
+              annotation_text="decline", annotation_position="top left",
+              fillcolor="green", opacity=0.25, line_width=0)
 fig.show()
 ```
-Call `help` on any of the autoshape functions in the Python interpreter to learn
-more (e.g., `help(fig.add_vline)`).
+### Reference
+
+More details are available about [layout shapes](/python/shapes/) and [annotations](/python/text-and-annotations). 
+
+Reference documentation is also available for [`add_hline`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html?highlight=add_hline#plotly.graph_objects.Figure.add_hline), [`add_vline`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html?highlight=add_vline#plotly.graph_objects.Figure.add_vline), [`add_hrect`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html?highlight=add_hrect#plotly.graph_objects.Figure.add_hrect), [`add_vrect`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html?highlight=add_vrect#plotly.graph_objects.Figure.add_vrect).