docstring refactoring in figure factory and various places (#1837)

Author: emmanuelle

packages/python/plotly/plotly/basedatatypes.py

@@ -1593,16 +1593,19 @@ def add_trace(self, trace, row=None, col=None, secondary_y=None):
 
         Examples
         --------
+
         >>> from plotly import subplots
         >>> import plotly.graph_objs as go
 
         Add two Scatter traces to a figure
+
         >>> fig = go.Figure()
         >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]))
         >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]))
 
 
         Add two Scatter traces to vertically stacked subplots
+
         >>> fig = subplots.make_subplots(rows=2)
         >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1)
         >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)
@@ -1665,15 +1668,18 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
 
         Examples
         --------
+
         >>> from plotly import subplots
         >>> import plotly.graph_objs as go
 
         Add two Scatter traces to a figure
+
         >>> fig = go.Figure()
         >>> fig.add_traces([go.Scatter(x=[1,2,3], y=[2,1,2]),
         ...                 go.Scatter(x=[1,2,3], y=[2,1,2])])
 
         Add two Scatter traces to vertically stacked subplots
+
         >>> fig = subplots.make_subplots(rows=2)
         >>> fig.add_traces([go.Scatter(x=[1,2,3], y=[2,1,2]),
         ...                 go.Scatter(x=[1,2,3], y=[2,1,2])],
@@ -1773,10 +1779,12 @@ def append_trace(self, trace, row, col):
 
         Examples
         --------
+
         >>> from plotly import tools
         >>> import plotly.graph_objs as go
-        # stack two subplots vertically
+        >>> # stack two subplots vertically
         >>> fig = tools.make_subplots(rows=2)
+
         This is the format of your plot grid:
         [ (1,1) x1,y1 ]
         [ (2,1) x2,y2 ]
@@ -2425,6 +2433,7 @@ def batch_update(self):
         --------
         For example, suppose we have a figure widget, `fig`, with a single
         trace.
+
         >>> import plotly.graph_objs as go
         >>> fig = go.FigureWidget(data=[{'y': [3, 4, 2]}])
 
@@ -2593,6 +2602,7 @@ def batch_animate(self, duration=500, easing="cubic-in-out"):
 
         2) Animate a change in the size and color of the trace's markers
         over 2 seconds using the elastic-in-out easing method
+
         >>> with fig.batch_update(duration=2000, easing='elastic-in-out'):
         ...     fig.data[0].marker.color = 'green'
         ...     fig.data[0].marker.size = 20
@@ -3055,6 +3065,7 @@ def _parent_path_str(self):
 
         Examples
         --------
+
         >>> import plotly.graph_objs as go
         >>> go.Layout()._parent_path_str
         ''
@@ -4582,6 +4593,7 @@ def on_hover(self, callback, append=False):
 
         Examples
         --------
+
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
@@ -4641,6 +4653,7 @@ def on_unhover(self, callback, append=False):
 
         Examples
         --------
+
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
@@ -4700,6 +4713,7 @@ def on_click(self, callback, append=False):
 
         Examples
         --------
+
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
@@ -4758,6 +4772,7 @@ def on_selection(self, callback, append=False):
 
         Examples
         --------
+
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
@@ -4823,6 +4838,7 @@ def on_deselect(self, callback, append=False):
 
         Examples
         --------
+
         >>> from plotly.callbacks import Points
         >>> points = Points()
 

packages/python/plotly/plotly/express/_doc.py

@@ -27,13 +27,13 @@
         colref_type,
         colref_desc,
         "Values from this column or array_like are used to position marks along the x axis in cartesian coordinates.",
-        "For horizontal `histogram`s, these values are used as inputs to `histfunc`.",
+        "For horizontal histograms, these values are used as inputs to `histfunc`.",
     ],
     y=[
         colref_type,
         colref_desc,
         "Values from this column or array_like are used to position marks along the y axis in cartesian coordinates.",
-        "For vertical `histogram`s, these values are used as inputs to `histfunc`.",
+        "For vertical histograms, these values are used as inputs to `histfunc`.",
     ],
     z=[
         colref_type,
@@ -455,6 +455,7 @@ def make_docstring(fn):
             if param in docs
             else "(documentation missing from map)"
         )
+
         param_type = docs[param][0]
         result += "%s: %s\n%s\n" % (param, param_type, param_desc)
     result += "\nReturns\n-------\n"

packages/python/plotly/plotly/figure_factory/_2d_density.py

@@ -51,49 +51,47 @@ def create_2d_density(
     :param (float) height: the height of the chart
     :param (float) width: the width of the chart
 
+    Examples
+    --------
+
     Example 1: Simple 2D Density Plot
-    ```
-    import plotly.plotly as py
-    from plotly.figure_factory create_2d_density
 
-    import numpy as np
+    >>> from plotly.figure_factory create_2d_density
+
+    >>> import numpy as np
 
-    # Make data points
-    t = np.linspace(-1,1.2,2000)
-    x = (t**3)+(0.3*np.random.randn(2000))
-    y = (t**6)+(0.3*np.random.randn(2000))
+    >>> # Make data points
+    >>> t = np.linspace(-1,1.2,2000)
+    >>> x = (t**3)+(0.3*np.random.randn(2000))
+    >>> y = (t**6)+(0.3*np.random.randn(2000))
 
-    # Create a figure
-    fig = create_2D_density(x, y)
+    >>> # Create a figure
+    >>> fig = create_2D_density(x, y)
 
-    # Plot the data
-    py.iplot(fig, filename='simple-2d-density')
-    ```
+    >>> # Plot the data
+    >>> fig.show()
 
     Example 2: Using Parameters
-    ```
-    import plotly.plotly as py
-    from plotly.figure_factory create_2d_density
 
-    import numpy as np
+    >>> from plotly.figure_factory create_2d_density
+
+    >>> import numpy as np
 
-    # Make data points
-    t = np.linspace(-1,1.2,2000)
-    x = (t**3)+(0.3*np.random.randn(2000))
-    y = (t**6)+(0.3*np.random.randn(2000))
+    >>> # Make data points
+    >>> t = np.linspace(-1,1.2,2000)
+    >>> x = (t**3)+(0.3*np.random.randn(2000))
+    >>> y = (t**6)+(0.3*np.random.randn(2000))
 
-    # Create custom colorscale
-    colorscale = ['#7A4579', '#D56073', 'rgb(236,158,105)',
-                  (1, 1, 0.2), (0.98,0.98,0.98)]
+    >>> # Create custom colorscale
+    >>> colorscale = ['#7A4579', '#D56073', 'rgb(236,158,105)',
+    ...              (1, 1, 0.2), (0.98,0.98,0.98)]
 
-    # Create a figure
-    fig = create_2D_density(
-        x, y, colorscale=colorscale,
-        hist_color='rgb(255, 237, 222)', point_size=3)
+    >>> # Create a figure
+    >>> fig = create_2D_density(x, y, colorscale=colorscale,
+    ...       hist_color='rgb(255, 237, 222)', point_size=3)
 
-    # Plot the data
-    py.iplot(fig, filename='use-parameters')
-    ```
+    >>> # Plot the data
+    >>> fig.show()
     """
 
     # validate x and y are filled with numbers only

packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py

@@ -84,17 +84,16 @@ def create_annotated_heatmap(
         call help(plotly.graph_objs.Heatmap)
 
     Example 1: Simple annotated heatmap with default configuration
-    ```
-    import plotly.plotly as py
-    import plotly.figure_factory as FF
 
-    z = [[0.300000, 0.00000, 0.65, 0.300000],
-         [1, 0.100005, 0.45, 0.4300],
-         [0.300000, 0.00000, 0.65, 0.300000],
-         [1, 0.100005, 0.45, 0.00000]]
+    >>> import plotly.figure_factory as ff
+
+    >>> z = [[0.300000, 0.00000, 0.65, 0.300000],
+    ...      [1, 0.100005, 0.45, 0.4300],
+    ...      [0.300000, 0.00000, 0.65, 0.300000],
+    ...      [1, 0.100005, 0.45, 0.00000]]
 
-    figure = FF.create_annotated_heatmap(z)
-    py.iplot(figure)
+    >>> fig = ff.create_annotated_heatmap(z)
+    >>> fig.show()
     ```
     """
 

packages/python/plotly/plotly/figure_factory/_bullet.py

@@ -238,49 +238,40 @@ def create_bullet(
         for more information on valid params.
 
     Example 1: Use a Dictionary
-    ```
-    import plotly
-    import plotly.plotly as py
-    import plotly.figure_factory as ff
-
-    data = [
-      {"label": "Revenue", "sublabel": "US$, in thousands",
-       "range": [150, 225, 300], "performance": [220,270], "point": [250]},
-      {"label": "Profit", "sublabel": "%", "range": [20, 25, 30],
-       "performance": [21, 23], "point": [26]},
-      {"label": "Order Size", "sublabel":"US$, average","range": [350, 500, 600],
-       "performance": [100,320],"point": [550]},
-      {"label": "New Customers", "sublabel": "count", "range": [1400, 2000, 2500],
-       "performance": [1000, 1650],"point": [2100]},
-      {"label": "Satisfaction", "sublabel": "out of 5","range": [3.5, 4.25, 5],
-       "performance": [3.2, 4.7], "point": [4.4]}
-    ]
-
-    fig = ff.create_bullet(
-        data, titles='label', subtitles='sublabel', markers='point',
-        measures='performance', ranges='range', orientation='h',
-        title='my simple bullet chart'
-    )
-    py.iplot(fig)
-    ```
+    
+    >>> import plotly.figure_factory as ff
+
+    >>> data = [
+    ...   {"label": "revenue", "sublabel": "us$, in thousands",
+    ...    "range": [150, 225, 300], "performance": [220,270], "point": [250]},
+    ...   {"label": "Profit", "sublabel": "%", "range": [20, 25, 30],
+    ...    "performance": [21, 23], "point": [26]},
+    ...   {"label": "Order Size", "sublabel":"US$, average","range": [350, 500, 600],
+    ...    "performance": [100,320],"point": [550]},
+    ...   {"label": "New Customers", "sublabel": "count", "range": [1400, 2000, 2500],
+    ...    "performance": [1000, 1650],"point": [2100]},
+    ...   {"label": "Satisfaction", "sublabel": "out of 5","range": [3.5, 4.25, 5],
+    ...    "performance": [3.2, 4.7], "point": [4.4]}
+    ... ]
+
+    >>> fig = ff.create_bullet(
+    ...     data, titles='label', subtitles='sublabel', markers='point',
+    ...     measures='performance', ranges='range', orientation='h',
+    ...     title='my simple bullet chart'
+    ... )
+    >>> fig.show()
 
     Example 2: Use a DataFrame with Custom Colors
-    ```
-    import plotly.plotly as py
-    import plotly.figure_factory as ff
-
-    import pandas as pd
 
-    data = pd.read_json('https://cdn.rawgit.com/plotly/datasets/master/BulletData.json')
+    >>> import plotly.figure_factory as ff
+    >>> import pandas as pd
+    >>> data = pd.read_json('https://cdn.rawgit.com/plotly/datasets/master/BulletData.json')
 
-    fig = ff.create_bullet(
-        data, titles='title', markers='markers', measures='measures',
-        orientation='v', measure_colors=['rgb(14, 52, 75)', 'rgb(31, 141, 127)'],
-        scatter_options={'marker': {'symbol': 'circle'}}, width=700
-
-    )
-    py.iplot(fig)
-    ```
+    >>> fig = ff.create_bullet(
+    ...     data, titles='title', markers='markers', measures='measures',
+    ...     orientation='v', measure_colors=['rgb(14, 52, 75)', 'rgb(31, 141, 127)'],
+    ...     scatter_options={'marker': {'symbol': 'circle'}}, width=700)
+    >>> fig.show()
     """
     # validate df
     if not pd: