document new methods add_shape add_annotation (#171)

Author: emmanuelle

python/shapes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.1.6
+      jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -55,8 +55,7 @@ fig.update_xaxes(range=[0, 7])
 fig.update_yaxes(range=[0, 2.5])
 
 # Add shapes
-fig.update_layout(
-    shapes=[
+fig.add_shape(
         # Line Vertical
         go.layout.Shape(
             type="line",
@@ -68,7 +67,8 @@ fig.update_layout(
                 color="RoyalBlue",
                 width=3
             )
-        ),
+))
+fig.add_shape(
         # Line Horizontal
         go.layout.Shape(
             type="line",
@@ -81,7 +81,8 @@ fig.update_layout(
                 width=4,
                 dash="dashdot",
             ),
-        ),
+    ))
+fig.add_shape(
         # Line Diagonal
         go.layout.Shape(
             type="line",
@@ -93,11 +94,9 @@ fig.update_layout(
                 color="MediumPurple",
                 width=4,
                 dash="dot",
-            ),
-        ),
-    ]
-)
-
+            )
+))
+fig.update_shapes(dict(xref='x', yref='y'))
 fig.show()
 ```
 
@@ -122,8 +121,7 @@ fig.update_xaxes(range=[0, 8])
 fig.update_yaxes(range=[0, 2])
 
 # Add shapes
-fig.update_layout(
-    shapes=[
+fig.add_shape(
         # Line reference to the axes
         go.layout.Shape(
             type="line",
@@ -137,7 +135,8 @@ fig.update_layout(
                 color="LightSeaGreen",
                 width=3,
             ),
-        ),
+        ))
+fig.add_shape(
         # Line reference to the plot
         go.layout.Shape(
             type="line",
@@ -152,7 +151,6 @@ fig.update_layout(
                 width=3,
             ),
         ),
-    ]
 )
 
 fig.show()
@@ -165,7 +163,7 @@ import plotly.graph_objects as go
 
 import numpy as np
 
-# Generate date
+# Generate data
 x0 = np.linspace(1, 3, 200)
 y0 = x0 * np.sin(np.power(x0, 2)) + 1
 
@@ -183,47 +181,38 @@ fig.update_layout(
 )
 
 # Add tangent line shapes
-fig.update_layout(
-    shapes=[
+fig.add_shape(
         go.layout.Shape(
             type="line",
             x0=1,
             y0=2.30756,
             x1=1.75,
             y1=2.30756,
-            opacity=0.7,
-            line=dict(
-                color="Crimson",
-                width=2.5,
-            ),
-        ),
+        ))
+fig.add_shape(
         go.layout.Shape(
             type="line",
             x0=2.5,
             y0=3.80796,
             x1=3.05,
             y1=3.80796,
-            opacity=0.7,
-            line=dict(
-                color="Crimson",
-                width=2.5,
-            ),
-        ),
+        ))
+fig.add_shape(
         go.layout.Shape(
             type="line",
             x0=1.90,
             y0=-1.1827,
             x1=2.50,
             y1=-1.1827,
-            opacity=0.7,
-            line=dict(
-                color="Crimson",
-                width=2.5,
-            ),
-        ),
-    ]
-)
-
+        ))
+fig.update_shapes(dict(
+    xref="x",
+    yref="y",
+    opacity=0.7,
+    line=dict(
+        color="Crimson",
+        width=2.5,
+        )))
 fig.show()
 ```
 
@@ -246,8 +235,7 @@ fig.update_xaxes(range=[0, 7], showgrid=False)
 fig.update_yaxes(range=[0, 3.5])
 
 # Add shapes
-fig.update_layout(
-    shapes=[
+fig.add_shape(
         # unfilled Rectangle
         go.layout.Shape(
             type="rect",
@@ -258,7 +246,8 @@ fig.update_layout(
             line=dict(
                 color="RoyalBlue",
             ),
-        ),
+        ))
+fig.add_shape(
         # filled Rectangle
         go.layout.Shape(
             type="rect",
@@ -271,10 +260,8 @@ fig.update_layout(
                 width=2,
             ),
             fillcolor="LightSkyBlue",
-        ),
-    ]
-)
-
+        ))
+fig.update_shapes(dict(xref='x', yref='y'))
 fig.show()
 ```
 
@@ -299,8 +286,7 @@ fig.update_xaxes(range=[0, 4], showgrid=False)
 fig.update_yaxes(range=[0, 4])
 
 # Add shapes
-fig.update_layout(
-    shapes=[
+fig.add_shape(
         # Rectangle reference to the axes
         go.layout.Shape(
             type="rect",
@@ -315,7 +301,8 @@ fig.update_layout(
                 width=3,
             ),
             fillcolor="LightSkyBlue",
-        ),
+        ))
+fig.add_shape(
         # Rectangle reference to the plot
         go.layout.Shape(
             type="rect",
@@ -330,9 +317,7 @@ fig.update_layout(
                 width=3,
             ),
             fillcolor="PaleTurquoise",
-        ),
-    ]
-)
+        ))
 
 fig.show()
 ```
@@ -592,37 +577,32 @@ fig.update_yaxes(
 )
 
 # Add circles
-fig.update_layout(
-    shapes=[
+fig.add_shape(
         go.layout.Shape(
-            opacity=0.3,
-            xref="x",
-            yref="y",
+            type="circle",
             fillcolor="blue",
             x0=0,
             y0=0,
             x1=2,
             y1=2,
-            type="circle",
-            line_color="blue",
-            layer="below"
-        ),
+            line_color="blue"
+        ))
+fig.add_shape(
         go.layout.Shape(
-            opacity=0.3,
-            xref="x",
-            yref="y",
+            type="circle",
             fillcolor="gray",
             x0=1.5,
             y0=0,
             x1=3.5,
             y1=2,
-            type="circle",
-            line_color="gray",
-            layer="below"
-        )
-    ],
-)
-
+            line_color="gray"
+        ))
+fig.update_shapes(dict(
+    opacity=0.3,
+    xref="x",
+    yref="y",
+    layer="below"
+))
 # Update figure dimensions
 fig.update_layout(
     margin=dict(

python/text-and-annotations.md

@@ -111,6 +111,8 @@ fig.show()
 
 ### Simple Annotation
 
+Annotations can be added to a figure using `fig.update_layout(annotations=[...])` or `fig.add_annotation`.
+
 ```python
 import plotly.graph_objects as go
 
@@ -164,33 +166,28 @@ fig.add_trace(go.Scatter(
     y=[0, 4, 5, 1, 2, 2, 3, 4, 2]
 ))
 
-fig.update_layout(
-    showlegend=False,
-    annotations=[
-        go.layout.Annotation(
+fig.add_annotation(
+    go.layout.Annotation(
             x=2,
             y=5,
-            xref="x",
-            yref="y",
-            text="dict Text",
-            showarrow=True,
-            arrowhead=7,
-            ax=0,
-            ay=-40
-        ),
-        go.layout.Annotation(
+            text="dict Text")
+)
+fig.add_annotation(
+    go.layout.Annotation(
             x=4,
             y=4,
+            text="dict Text 2")
+)
+fig.update_annotations(dict(
             xref="x",
             yref="y",
-            text="dict Text 2",
             showarrow=True,
             arrowhead=7,
             ax=0,
             ay=-40
-        )
-    ]
-)
+))
+
+fig.update_layout(showlegend=False)
 
 fig.show()
 ```
@@ -347,37 +344,35 @@ fig.add_trace(go.Scatter(
     y=[0, 4, 5, 1, 2, 2, 3, 4, 2]
 ))
 
-fig.update_layout(
-    showlegend=False,
-    annotations=[
-        go.layout.Annotation(
-            x=2,
-            y=5,
-            xref="x",
-            yref="y",
-            text="max=5",
-            showarrow=True,
-            font=dict(
-                family="Courier New, monospace",
-                size=16,
-                color="#ffffff"
+fig.add_annotation(
+    go.layout.Annotation(
+        x=2,
+        y=5,
+        xref="x",
+        yref="y",
+        text="max=5",
+        showarrow=True,
+        font=dict(
+            family="Courier New, monospace",
+            size=16,
+            color="#ffffff"
             ),
-            align="center",
-            arrowhead=2,
-            arrowsize=1,
-            arrowwidth=2,
-            arrowcolor="#636363",
-            ax=20,
-            ay=-30,
-            bordercolor="#c7c7c7",
-            borderwidth=2,
-            borderpad=4,
-            bgcolor="#ff7f0e",
-            opacity=0.8
+        align="center",
+        arrowhead=2,
+        arrowsize=1,
+        arrowwidth=2,
+        arrowcolor="#636363",
+        ax=20,
+        ay=-30,
+        bordercolor="#c7c7c7",
+        borderwidth=2,
+        borderpad=4,
+        bgcolor="#ff7f0e",
+        opacity=0.8
         )
-    ]
 )
 
+fig.update_layout(showlegend=False)
 fig.show()
 ```