From a02321208504ffd2e5f1be0081dce40e71390c97 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Fri, 22 Nov 2019 15:10:19 -0500
Subject: [PATCH 01/18] first round of changes towards doctesting

---
 .../python/plotly/plotly/basedatatypes.py     | 49 ++++++++---
 .../plotly/figure_factory/_2d_density.py      |  9 +-
 .../figure_factory/_annotated_heatmap.py      |  1 -
 .../plotly/figure_factory/_candlestick.py     | 48 +++-------
 .../plotly/figure_factory/_dendrogram.py      |  2 +-
 .../plotly/plotly/figure_factory/_distplot.py |  4 +-
 .../plotly/figure_factory/_facet_grid.py      |  6 +-
 .../plotly/plotly/figure_factory/_ohlc.py     | 88 +------------------
 .../plotly/plotly/figure_factory/_quiver.py   |  2 +-
 .../plotly/figure_factory/_streamline.py      |  7 +-
 .../plotly/figure_factory/_ternary_contour.py | 18 ++--
 .../plotly/plotly/figure_factory/_trisurf.py  |  2 +-
 .../plotly/plotly/figure_factory/_violin.py   |  1 -
 .../plotly/plotly/graph_objs/__init__.py      | 14 +--
 .../python/plotly/plotly/io/_templates.py     |  6 +-
 .../python/plotly/plotly/offline/offline.py   |  4 +-
 packages/python/plotly/plotly/subplots.py     | 44 ++++++----
 packages/python/plotly/plotly/utils.py        |  8 +-
 18 files changed, 125 insertions(+), 188 deletions(-)

diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py
index 22469d43034..6d24da3c015 100644
--- a/packages/python/plotly/plotly/basedatatypes.py
+++ b/packages/python/plotly/plotly/basedatatypes.py
@@ -458,8 +458,9 @@ def update(self, dict1=None, overwrite=False, **kwargs):
         --------
         >>> import plotly.graph_objs as go
         >>> fig = go.Figure(data=[{'y': [1, 2, 3]}])
-        >>> fig.update(data=[{'y': [4, 5, 6]}])
-        >>> fig.to_plotly_json()
+        >>> fig.update(data=[{'y': [4, 5, 6]}]) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.to_plotly_json() # doctest: +SKIP
             {'data': [{'type': 'scatter',
                'uid': 'e86a7c7a-346a-11e8-8aa8-a0999b0c017b',
                'y': array([4, 5, 6], dtype=int32)}],
@@ -468,8 +469,9 @@ def update(self, dict1=None, overwrite=False, **kwargs):
         >>> fig = go.Figure(layout={'xaxis':
         ...                         {'color': 'green',
         ...                          'range': [0, 1]}})
-        >>> fig.update({'layout': {'xaxis': {'color': 'pink'}}})
-        >>> fig.to_plotly_json()
+        >>> fig.update({'layout': {'xaxis': {'color': 'pink'}}}) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.to_plotly_json() # doctest: +SKIP
             {'data': [],
              'layout': {'xaxis':
                         {'color': 'pink',
@@ -1128,6 +1130,8 @@ def plotly_restyle(self, restyle_data, trace_indexes=None, **kwargs):
             example, the following command would be used to update the 'x'
             property of the first trace to the list [1, 2, 3]
 
+            >>> import plotly.graph_objects as go
+            >>> fig = go.Figure(go.Scatter(x=[2, 4, 6]))
             >>> fig.plotly_restyle({'x': [[1, 2, 3]]}, 0)
 
         trace_indexes : int or list of int
@@ -1586,15 +1590,19 @@ def add_trace(self, trace, row=None, col=None, secondary_y=None):
         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]))
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) #doctest: +ELLIPSIS
+        Figure(...)
 
 
         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)
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) #doctest: +ELLIPSIS
+        Figure(...)
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1) #doctest: +ELLIPSIS
+        Figure(...)
         """
         # Make sure we have both row and col or neither
         if row is not None and col is None:
@@ -1662,14 +1670,16 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
 
         >>> 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])])
+        ...                 go.Scatter(x=[1,2,3], y=[2,1,2])]) #doctest: +ELLIPSIS
+        Figure(...)
 
         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])],
-        ...                 rows=[1, 2], cols=[1, 1])
+        ...                 rows=[1, 2], cols=[1, 1]) #doctest: +ELLIPSIS
+        Figure(...)
         """
 
         # Validate traces
@@ -2152,11 +2162,12 @@ def _build_dispatch_plan(key_path_strs):
 
         Examples
         --------
+
         >>> key_path_strs = ['xaxis.rangeselector.font.color',
         ...                  'xaxis.rangeselector.bgcolor']
 
-        >>> BaseFigure._build_dispatch_plan(key_path_strs)
-            {(): {('xaxis',),
+        >>> BaseFigure._build_dispatch_plan(key_path_strs) #doctest: +SKIP
+            {(): {'xaxis',
                   ('xaxis', 'rangeselector'),
                   ('xaxis', 'rangeselector', 'bgcolor'),
                   ('xaxis', 'rangeselector', 'font'),
@@ -2589,7 +2600,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'):
+        >>> with fig.batch_animate(duration=2000, easing='elastic-in-out'):
         ...     fig.data[0].marker.color = 'green'
         ...     fig.data[0].marker.size = 20
         """
@@ -4088,6 +4099,8 @@ def on_change(self, callback, *args, **kwargs):
         Register callback that prints out the range extents of the xaxis and
         yaxis whenever either either of them changes.
 
+        >>> import plotly.graph_objects as go
+        >>> fig = go.Figure(go.Scatter(x=[1, 2], y=[1, 0]))
         >>> fig.layout.on_change(
         ...   lambda obj, xrange, yrange: print("%s-%s" % (xrange, yrange)),
         ...   ('xaxis', 'range'), ('yaxis', 'range'))
@@ -4572,6 +4585,7 @@ def on_hover(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
@@ -4579,6 +4593,7 @@ def on_hover(self, callback, append=False):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_hover(hover_fn)
 
         Note: The creation of the `points` and `state` objects is optional,
@@ -4632,6 +4647,7 @@ def on_unhover(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
@@ -4639,6 +4655,7 @@ def on_unhover(self, callback, append=False):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_unhover(unhover_fn)
 
         Note: The creation of the `points` and `state` objects is optional,
@@ -4692,6 +4709,7 @@ def on_click(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
@@ -4699,6 +4717,7 @@ def on_click(self, callback, append=False):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_click(click_fn)
 
         Note: The creation of the `points` and `state` objects is optional,
@@ -4751,6 +4770,7 @@ def on_selection(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
@@ -4758,6 +4778,7 @@ def on_selection(self, callback, append=False):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_selection(selection_fn)
 
         Note: The creation of the `points` object is optional,
@@ -4817,6 +4838,7 @@ def on_deselect(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
@@ -4824,6 +4846,7 @@ def on_deselect(self, callback, append=False):
         ...     inds = points.point_inds
         ...     # Do something
 
+        >>> trace = go.Scatter(x=[1, 2], y=[3, 0])
         >>> trace.on_deselect(deselect_fn)
 
         Note: The creation of the `points` object is optional,
diff --git a/packages/python/plotly/plotly/figure_factory/_2d_density.py b/packages/python/plotly/plotly/figure_factory/_2d_density.py
index 5a96d4b3718..e63b2af2e9b 100644
--- a/packages/python/plotly/plotly/figure_factory/_2d_density.py
+++ b/packages/python/plotly/plotly/figure_factory/_2d_density.py
@@ -56,8 +56,7 @@ def create_2d_density(
 
     Example 1: Simple 2D Density Plot
 
-    >>> from plotly.figure_factory create_2d_density
-
+    >>> from plotly.figure_factory import create_2d_density
     >>> import numpy as np
 
     >>> # Make data points
@@ -66,14 +65,14 @@ def create_2d_density(
     >>> y = (t**6)+(0.3*np.random.randn(2000))
 
     >>> # Create a figure
-    >>> fig = create_2D_density(x, y)
+    >>> fig = create_2d_density(x, y)
 
     >>> # Plot the data
     >>> fig.show()
 
     Example 2: Using Parameters
 
-    >>> from plotly.figure_factory create_2d_density
+    >>> from plotly.figure_factory import create_2d_density
 
     >>> import numpy as np
 
@@ -87,7 +86,7 @@ def create_2d_density(
     ...              (1, 1, 0.2), (0.98,0.98,0.98)]
 
     >>> # Create a figure
-    >>> fig = create_2D_density(x, y, colorscale=colorscale,
+    >>> fig = create_2d_density(x, y, colorscale=colorscale,
     ...       hist_color='rgb(255, 237, 222)', point_size=3)
 
     >>> # Plot the data
diff --git a/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py b/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
index c3b1e2fa989..d158afe3171 100644
--- a/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
+++ b/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
@@ -94,7 +94,6 @@ def create_annotated_heatmap(
 
     >>> fig = ff.create_annotated_heatmap(z)
     >>> fig.show()
-    ```
     """
 
     # Avoiding mutables in the call signature
diff --git a/packages/python/plotly/plotly/figure_factory/_candlestick.py b/packages/python/plotly/plotly/figure_factory/_candlestick.py
index db4cc507355..153b49f42ff 100644
--- a/packages/python/plotly/plotly/figure_factory/_candlestick.py
+++ b/packages/python/plotly/plotly/figure_factory/_candlestick.py
@@ -125,51 +125,32 @@ def create_candlestick(open, high, low, close, dates=None, direction="both", **k
 
     >>> from plotly.figure_factory import create_candlestick
     >>> from datetime import datetime
+    >>> import pandas as pd
 
-    >>> import pandas.io.data as web
-
-    >>> df = web.DataReader("aapl", 'yahoo', datetime(2007, 10, 1), datetime(2009, 4, 1))
-    >>> fig = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index)
+    >>> df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+    >>> fig = create_candlestick(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'],
+    ...                          dates=df.index)
     >>> fig.show()
 
-    Example 2: Add text and annotations to the candlestick chart
-    
-    >>> fig = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index)
-    >>> # Update the fig - all options here: https://plot.ly/python/reference/#Layout
-    >>> fig['layout'].update({
-        'title': 'The Great Recession',
-        'yaxis': {'title': 'AAPL Stock'},
-        'shapes': [{
-            'x0': '2007-12-01', 'x1': '2007-12-01',
-            'y0': 0, 'y1': 1, 'xref': 'x', 'yref': 'paper',
-            'line': {'color': 'rgb(30,30,30)', 'width': 1}
-        }],
-        'annotations': [{
-            'x': '2007-12-01', 'y': 0.05, 'xref': 'x', 'yref': 'paper',
-            'showarrow': False, 'xanchor': 'left',
-            'text': 'Official start of the recession'
-        }]
-    })
-    >>> fig.show()
+    Example 2: Customize the candlestick colors
 
-    Example 3: Customize the candlestick colors
-    
     >>> from plotly.figure_factory import create_candlestick
     >>> from plotly.graph_objs import Line, Marker
     >>> from datetime import datetime
 
-    >>> import pandas.io.data as web
-
-    >>> df = web.DataReader("aapl", 'yahoo', datetime(2008, 1, 1), datetime(2009, 4, 1))
+    >>> import pandas as pd
+    >>> df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
 
     >>> # Make increasing candlesticks and customize their color and name
-    >>> fig_increasing = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index,
+    >>> fig_increasing = create_candlestick(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'],
+    ...     dates=df.index,
     ...     direction='increasing', name='AAPL',
     ...     marker=Marker(color='rgb(150, 200, 250)'),
     ...     line=Line(color='rgb(150, 200, 250)'))
 
     >>> # Make decreasing candlesticks and customize their color and name
-    >>> fig_decreasing = create_candlestick(df.Open, df.High, df.Low, df.Close, dates=df.index,
+    >>> fig_decreasing = create_candlestick(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'],
+    ...     dates=df.index,
     ...     direction='decreasing',
     ...     marker=Marker(color='rgb(128, 128, 128)'),
     ...     line=Line(color='rgb(128, 128, 128)'))
@@ -178,11 +159,11 @@ def create_candlestick(open, high, low, close, dates=None, direction="both", **k
     >>> fig = fig_increasing
 
     >>> # Add decreasing data with .extend()
-    >>> fig['data'].extend(fig_decreasing['data'])
+    >>> fig.add_trace(fig_decreasing['data']) # doctest: +SKIP
     >>> fig.show()
 
-    Example 4: Candlestick chart with datetime objects
-    
+    Example 3: Candlestick chart with datetime objects
+ 
     >>> from plotly.figure_factory import create_candlestick
 
     >>> from datetime import datetime
@@ -202,7 +183,6 @@ def create_candlestick(open, high, low, close, dates=None, direction="both", **k
     >>> fig = create_candlestick(open_data, high_data,
     ...     low_data, close_data, dates=dates)
     >>> fig.show()
-
     """
     if dates is not None:
         utils.validate_equal_length(open, high, low, close, dates)
diff --git a/packages/python/plotly/plotly/figure_factory/_dendrogram.py b/packages/python/plotly/plotly/figure_factory/_dendrogram.py
index 14ae27bccce..2e1897835c8 100644
--- a/packages/python/plotly/plotly/figure_factory/_dendrogram.py
+++ b/packages/python/plotly/plotly/figure_factory/_dendrogram.py
@@ -58,7 +58,7 @@ def create_dendrogram(
     >>> X = np.random.rand(5,5)
     >>> names = ['Jack', 'Oxana', 'John', 'Chelsea', 'Mark']
     >>> dendro = create_dendrogram(X, orientation='right', labels=names)
-    >>> dendro['layout'].update({'width':700, 'height':500})
+    >>> dendro.update_layout({'width':700, 'height':500}) # doctest: +SKIP
     >>> dendro.show()
 
     Example 3: Dendrogram with Pandas
diff --git a/packages/python/plotly/plotly/figure_factory/_distplot.py b/packages/python/plotly/plotly/figure_factory/_distplot.py
index 2808931abe9..6c4ae79f1ef 100644
--- a/packages/python/plotly/plotly/figure_factory/_distplot.py
+++ b/packages/python/plotly/plotly/figure_factory/_distplot.py
@@ -130,7 +130,7 @@ def create_distplot(
     ...     hist_data, group_labels, rug_text=rug_text_all, bin_size=.2)
 
     >>> # Add title
-    >>> fig['layout'].update(title='Dist Plot')
+    >>> fig.update_layout(title='Dist Plot') # doctest: +SKIP
     >>> fig.show()
 
 
@@ -159,7 +159,7 @@ def create_distplot(
     >>> import pandas as pd
 
     >>> df = pd.DataFrame({'2012': np.random.randn(200),
-    >>>                    '2013': np.random.randn(200)+1})
+    ...                    '2013': np.random.randn(200)+1})
     >>> fig = create_distplot([df[c] for c in df.columns], df.columns)
     >>> fig.show()
     """
diff --git a/packages/python/plotly/plotly/figure_factory/_facet_grid.py b/packages/python/plotly/plotly/figure_factory/_facet_grid.py
index 95e0f70edec..010df401982 100644
--- a/packages/python/plotly/plotly/figure_factory/_facet_grid.py
+++ b/packages/python/plotly/plotly/figure_factory/_facet_grid.py
@@ -754,7 +754,8 @@ def create_facet_grid(
 
     >>> import plotly.figure_factory as ff
     >>> import pandas as pd
-    >>> mpg = pd.read_table('https://raw.githubusercontent.com/plotly/datasets/master/mpg_2017.txt')
+    >>> mtcars = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/mtcars.csv')
+    >>> mtcars.cyl = mtcars.cyl.astype(str)
     >>> fig = ff.create_facet_grid(
     ...     mtcars,
     ...     x='mpg',
@@ -770,9 +771,10 @@ def create_facet_grid(
     >>> import plotly.figure_factory as ff
     >>> import pandas as pd
     >>> tips = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/tips.csv')
+    >>> tips.size = tips.size.astype(str)
 
     >>> fig = ff.create_facet_grid(
-    >>>     tips,
+    ...     tips,
     ...     x='total_bill',
     ...     y='tip',
     ...     facet_row='sex',
diff --git a/packages/python/plotly/plotly/figure_factory/_ohlc.py b/packages/python/plotly/plotly/figure_factory/_ohlc.py
index 3122bb0a6c5..ed3d647fbe8 100644
--- a/packages/python/plotly/plotly/figure_factory/_ohlc.py
+++ b/packages/python/plotly/plotly/figure_factory/_ohlc.py
@@ -161,91 +161,9 @@ def create_ohlc(open, high, low, close, dates=None, direction="both", **kwargs):
     >>> from plotly.figure_factory import create_ohlc
     >>> from datetime import datetime
 
-    >>> import pandas.io.data as web
-
-    >>> df = web.DataReader("aapl", 'yahoo', datetime(2008, 8, 15),
-    ...                     datetime(2008, 10, 15))
-    >>> fig = create_ohlc(df.Open, df.High, df.Low, df.Close, dates=df.index)
-    >>> fig.show()
-
-    Example 2: Add text and annotations to the OHLC chart
-
-    >>> from plotly.figure_factory import create_ohlc
-    >>> from datetime import datetime
-
-    >>> import pandas.io.data as web
-
-    >>> df = web.datareader("aapl", 'yahoo', datetime(2008, 8, 15),
-    ...                     datetime(2008, 10, 15))
-    >>> fig = create_ohlc(df.open, df.high, df.low, df.close, dates=df.index)
-
-    >>> # update the fig - options here: https://plot.ly/python/reference/#layout
-    >>> fig['layout'].update({
-    ...     'title': 'the great recession',
-    ...     'yaxis': {'title': 'aapl stock'},
-    ...     'shapes': [{
-    ...         'x0': '2008-09-15', 'x1': '2008-09-15', 'type': 'line',
-    ...         'y0': 0, 'y1': 1, 'xref': 'x', 'yref': 'paper',
-    ...         'line': {'color': 'rgb(40,40,40)', 'width': 0.5}
-    ...     }],
-    ...     'annotations': [{
-    ...         'text': "the fall of lehman brothers",
-    ...         'x': '2008-09-15', 'y': 1.02,
-    ...         'xref': 'x', 'yref': 'paper',
-    ...         'showarrow': false, 'xanchor': 'left'
-    ...     }]
-    ... })
-    >>> fig.show()
-
-    Example 3: Customize the OHLC colors
-
-    >>> from plotly.figure_factory import create_ohlc
-    >>> from plotly.graph_objs import Line, Marker
-    >>> from datetime import datetime
-
-    >>> import pandas.io.data as web
-
-    >>> df = web.DataReader("aapl", 'yahoo', datetime(2008, 1, 1),
-    ...                     datetime(2009, 4, 1))
-
-    >>> # Make increasing ohlc sticks and customize their color and name
-    >>> fig_increasing = create_ohlc(df.Open, df.High, df.Low, df.Close,
-    ...                              dates=df.index, direction='increasing',
-    ...                              name='AAPL',
-    ...                              line=Line(color='rgb(150, 200, 250)'))
-
-    >>> # Make decreasing ohlc sticks and customize their color and name
-    >>> fig_decreasing = create_ohlc(df.Open, df.High, df.Low, df.Close,
-    ...                              dates=df.index, direction='decreasing',
-    ...                              line=Line(color='rgb(128, 128, 128)'))
-
-    >>> # Initialize the figure
-    >>> fig = fig_increasing
-
-    >>> # Add decreasing data with .extend()
-    >>> fig['data'].extend(fig_decreasing['data'])
-    >>> fig.show()
-
-
-    Example 4: OHLC chart with datetime objects
-
-    >>> from plotly.figure_factory import create_ohlc
-
-    >>> from datetime import datetime
-
-    >>> # Add data
-    >>> open_data = [33.0, 33.3, 33.5, 33.0, 34.1]
-    >>> high_data = [33.1, 33.3, 33.6, 33.2, 34.8]
-    >>> low_data = [32.7, 32.7, 32.8, 32.6, 32.8]
-    >>> close_data = [33.0, 32.9, 33.3, 33.1, 33.1]
-    >>> dates = [datetime(year=2013, month=10, day=10),
-    ...          datetime(year=2013, month=11, day=10),
-    ...          datetime(year=2013, month=12, day=10),
-    ...          datetime(year=2014, month=1, day=10),
-    ...          datetime(year=2014, month=2, day=10)]
-
-    >>> # Create ohlc
-    >>> fig = create_ohlc(open_data, high_data, low_data, close_data, dates=dates)
+    >>> import pandas as pd
+    >>> df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
+    >>> fig = create_ohlc(df['AAPL.Open'], df['AAPL.High'], df['AAPL.Low'], df['AAPL.Close'], dates=df.index)
     >>> fig.show()
     """
     if dates is not None:
diff --git a/packages/python/plotly/plotly/figure_factory/_quiver.py b/packages/python/plotly/plotly/figure_factory/_quiver.py
index e9503515ea1..f40df33d451 100644
--- a/packages/python/plotly/plotly/figure_factory/_quiver.py
+++ b/packages/python/plotly/plotly/figure_factory/_quiver.py
@@ -75,7 +75,7 @@ def create_quiver(
     ...                     name='Wind Velocity', line=dict(width=1))
 
     >>> # Add title to layout
-    >>> fig['layout'].update(title='Quiver Plot')
+    >>> fig.update_layout(title='Quiver Plot') # doctest: +SKIP
     >>> fig.show()
 
 
diff --git a/packages/python/plotly/plotly/figure_factory/_streamline.py b/packages/python/plotly/plotly/figure_factory/_streamline.py
index caf42d704e4..23be4210e46 100644
--- a/packages/python/plotly/plotly/figure_factory/_streamline.py
+++ b/packages/python/plotly/plotly/figure_factory/_streamline.py
@@ -62,6 +62,7 @@ def create_streamline(
     Example 1: Plot simple streamline and increase arrow size
 
     >>> from plotly.figure_factory import create_streamline
+    >>> import plotly.graph_objects as go
     >>> import numpy as np
     >>> import math
 
@@ -102,10 +103,10 @@ def create_streamline(
     >>> fig = create_streamline(x, y, u_s, v_s, density=2, name='streamline')
 
     >>> # Add source point
-    >>> point = Scatter(x=[x_s], y=[y_s], mode='markers',
-    ...                 marker=Marker(size=14), name='source point')
+    >>> point = go.Scatter(x=[x_s], y=[y_s], mode='markers',
+    ...                    marker_size=14, name='source point')
 
-    >>> fig['data'].append(point)
+    >>> fig.add_trace(point) # doctest: +SKIP
     >>> fig.show()
     """
     utils.validate_equal_length(x, y)
diff --git a/packages/python/plotly/plotly/figure_factory/_ternary_contour.py b/packages/python/plotly/plotly/figure_factory/_ternary_contour.py
index e48fea65673..49d1e60dc68 100644
--- a/packages/python/plotly/plotly/figure_factory/_ternary_contour.py
+++ b/packages/python/plotly/plotly/figure_factory/_ternary_contour.py
@@ -584,33 +584,33 @@ def create_ternary_contour(
     >>> c = 1 - a - b
     >>> # Values to be displayed as contours
     >>> z = a * b * c
-    >>> fig = ff.create_ternarycontour(np.stack((a, b, c)), z)
+    >>> fig = ff.create_ternary_contour(np.stack((a, b, c)), z)
     >>> fig.show()
 
     It is also possible to give only two barycentric coordinates for each
     point, since the sum of the three coordinates is one:
 
-    >>> fig = ff.create_ternarycontour(np.stack((a, b)), z)
+    >>> fig = ff.create_ternary_contour(np.stack((a, b)), z)
 
 
     Example 2: ternary contour plot with line contours
 
-    >>> fig = ff.create_ternarycontour(np.stack((a, b, c)), z, coloring='lines')
+    >>> fig = ff.create_ternary_contour(np.stack((a, b, c)), z, coloring='lines')
 
     Example 3: customize number of contours
 
-    >>> fig = ff.create_ternarycontour(np.stack((a, b, c)), z, ncontours=8)
+    >>> fig = ff.create_ternary_contour(np.stack((a, b, c)), z, ncontours=8)
 
     Example 4: superimpose contour plot and original data as markers
 
-    >>> fig = ff.create_ternarycontour(np.stack((a, b, c)), z, coloring='lines',
-                                   showmarkers=True)
+    >>> fig = ff.create_ternary_contour(np.stack((a, b, c)), z, coloring='lines',
+    ...                                 showmarkers=True)
 
     Example 5: customize title and pole labels
 
-    >>> fig = ff.create_ternarycontour(np.stack((a, b, c)), z,
-    ...                               title='Ternary plot',
-    ...                               pole_labels=['clay', 'quartz', 'fledspar'])
+    >>> fig = ff.create_ternary_contour(np.stack((a, b, c)), z,
+    ...                                 title='Ternary plot',
+    ...                                 pole_labels=['clay', 'quartz', 'fledspar'])
     """
     if scipy_interp is None:
         raise ImportError(
diff --git a/packages/python/plotly/plotly/figure_factory/_trisurf.py b/packages/python/plotly/plotly/figure_factory/_trisurf.py
index caf7353d837..f3f55d8d1e0 100644
--- a/packages/python/plotly/plotly/figure_factory/_trisurf.py
+++ b/packages/python/plotly/plotly/figure_factory/_trisurf.py
@@ -456,7 +456,7 @@ def create_trisurf(
     >>> color_choices = ['rgb(0, 0, 0)', '#6c4774', '#d6c7dd']
 
     >>> for index in range(len(simplices)):
-    >>>     colors.append(random.choice(color_choices))
+    ...     colors.append(random.choice(color_choices))
 
     >>> fig = create_trisurf(
     ...     x, y, z, simplices,
diff --git a/packages/python/plotly/plotly/figure_factory/_violin.py b/packages/python/plotly/plotly/figure_factory/_violin.py
index c2bc612cfce..7a48ccaeb75 100644
--- a/packages/python/plotly/plotly/figure_factory/_violin.py
+++ b/packages/python/plotly/plotly/figure_factory/_violin.py
@@ -496,7 +496,6 @@ def create_violin(
 
     >>> # create list of random values
     >>> data_list = np.random.randn(100)
-    >>> data_list.tolist()
 
     >>> # create violin fig
     >>> fig = create_violin(data_list, colors='#604d9e')
diff --git a/packages/python/plotly/plotly/graph_objs/__init__.py b/packages/python/plotly/plotly/graph_objs/__init__.py
index 140fd58fccc..9a204d2dbbf 100644
--- a/packages/python/plotly/plotly/graph_objs/__init__.py
+++ b/packages/python/plotly/plotly/graph_objs/__init__.py
@@ -95064,27 +95064,31 @@ def template(self):
         annotation or a logo image, for example. To omit one of these
         items on the plot, make an item with matching
         `templateitemname` and `visible: false`.
-    
+
         The 'template' property is an instance of Template
         that may be specified as:
           - An instance of plotly.graph_objs.layout.Template
           - A dict of string/value properties that will be passed
             to the Template constructor
-    
+
             Supported dict properties:
-                
+
                 data
                     plotly.graph_objects.layout.template.Data
                     instance or dict with compatible properties
                 layout
                     plotly.graph_objects.Layout instance or dict
                     with compatible properties
-    
+
           - The name of a registered template where current registered templates
             are stored in the plotly.io.templates configuration object. The names
             of all registered templates can be retrieved with:
+
                 >>> import plotly.io as pio
-                >>> list(pio.templates)
+                >>> list(pio.templates) # doctest: +ELLIPSIS
+                ['ggplot2', 'seaborn', 'simple_white', 'plotly', 'plotly_white', 'plotly_dark', ...]
+
+
           - A string containing multiple registered template names, joined on '+'
             characters (e.g. 'template1+template2'). In this case the resulting
             template is computed by merging together the collection of registered 
diff --git a/packages/python/plotly/plotly/io/_templates.py b/packages/python/plotly/plotly/io/_templates.py
index 8395a20dffb..b2e546a288e 100644
--- a/packages/python/plotly/plotly/io/_templates.py
+++ b/packages/python/plotly/plotly/io/_templates.py
@@ -376,11 +376,11 @@ def to_templated(fig, skip=("title", "text")):
 
     >>> fig = go.Figure(layout={'title': 'Figure Title',
     ...                         'font': {'size': 20, 'family': 'Courier'}})
-    >>> fig
+    >>> fig # doctest: +NORMALIZE_WHITESPACE
     Figure({
         'data': [],
-        'layout': {'title': 'Figure Title',
-                   'font': {'family': 'Courier', 'size': 20}}
+        'layout': {'font': {'family': 'Courier', 'size': 20},
+                   'template': '...', 'title': {'text': 'Figure Title'}}
     })
 
     Convert to a figure with a template. Note how the 'font' properties have
diff --git a/packages/python/plotly/plotly/offline/offline.py b/packages/python/plotly/plotly/offline/offline.py
index c7d458b1452..30674ee19da 100644
--- a/packages/python/plotly/plotly/offline/offline.py
+++ b/packages/python/plotly/plotly/offline/offline.py
@@ -81,10 +81,10 @@ def get_plotlyjs():
     ...        {div2}
     ...     </body>
     ... </html>
-    ...'''.format(plotlyjs=get_plotlyjs(), div1=div1, div2=div2)
+    ... '''.format(plotlyjs=get_plotlyjs(), div1=div1, div2=div2)
 
     >>> with open('multi_plot.html', 'w') as f:
-    ...      f.write(html)
+    ...      f.write(html) # doctest: +SKIP
     """
     path = os.path.join("package_data", "plotly.min.js")
     plotlyjs = pkgutil.get_data("plotly", path).decode("utf-8")
diff --git a/packages/python/plotly/plotly/subplots.py b/packages/python/plotly/plotly/subplots.py
index 63adab47e3a..9f2075e7cb1 100644
--- a/packages/python/plotly/plotly/subplots.py
+++ b/packages/python/plotly/plotly/subplots.py
@@ -235,15 +235,17 @@ def make_subplots(
 
     >>> # Stack two subplots vertically, and add a scatter trace to each
     >>> from plotly.subplots import make_subplots
-    ... import plotly.graph_objs as go
-    ... fig = make_subplots(rows=2)
+    >>> import plotly.graph_objects as go
+    >>> fig = make_subplots(rows=2)
 
     This is the format of your plot grid:
     [ (1,1) xaxis1,yaxis1 ]
     [ (2,1) xaxis2,yaxis2 ]
 
-    >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1)
-    ... fig.add_scatter(y=[1, 3, 2], row=2, col=1)
+    >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
+    Figure(...)
+    >>> fig.add_scatter(y=[1, 3, 2], row=2, col=1) # doctest: +ELLIPSIS
+    Figure(...)
 
     or see Figure.append_trace
 
@@ -256,23 +258,28 @@ def make_subplots(
     [ (1,1) xaxis1,yaxis1 ]
     [ (2,1) xaxis2,yaxis2 ]
 
-    >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1)
-    ... fig.add_scatter(y=[1, 3, 2], row=2, col=1)
+    >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
+    Figure(...)
+    >>> fig.add_scatter(y=[1, 3, 2], row=2, col=1) # doctest: +ELLIPSIS
+    Figure(...)
 
     Example 3:
 
     >>> # irregular subplot layout (more examples below under 'specs')
     >>> fig = make_subplots(rows=2, cols=2,
-                            specs=[[{}, {}],
-                                   [{'colspan': 2}, None]])
+    ...                     specs=[[{}, {}],
+    ...                     [{'colspan': 2}, None]])
 
     This is the format of your plot grid:
     [ (1,1) xaxis1,yaxis1 ]  [ (1,2) xaxis2,yaxis2 ]
     [ (2,1) xaxis3,yaxis3           -              ]
 
-    >>> 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=1, col=2)
-    ... fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)
+    >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) # doctest: +ELLIPSIS
+    Figure(...)
+    >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=2) # doctest: +ELLIPSIS
+    Figure(...)
+    >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1) # doctest: +ELLIPSIS
+    Figure(...)
 
     Example 4:
 
@@ -285,8 +292,10 @@ def make_subplots(
     With insets:
     [ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 ]
 
-    >>> fig.add_scatter(x=[1,2,3], y=[2,1,1])
-    ... fig.add_scatter(x=[1,2,3], y=[2,1,2], xaxis='x2', yaxis='y2')
+    >>> fig.add_scatter(x=[1,2,3], y=[2,1,1]) # doctest: +ELLIPSIS
+    Figure(...)
+    >>> fig.add_scatter(x=[1,2,3], y=[2,1,2], xaxis='x2', yaxis='y2') # doctest: +ELLIPSIS
+    Figure(...)
 
     Example 5:
 
@@ -297,8 +306,10 @@ def make_subplots(
     [ (1,1) x1,y1 ]
     [ (2,1) x2,y2 ]
 
-    >>> fig.add_scatter(x=[1,2,3], y=[2,1,2], row=1, col=1)
-    >>> fig.add_bar(x=[1,2,3], y=[2,1,2], row=2, col=1)
+    >>> fig.add_scatter(x=[1,2,3], y=[2,1,2], row=1, col=1) # doctest: +ELLIPSIS
+    Figure(...)
+    >>> fig.add_bar(x=[1,2,3], y=[2,1,2], row=2, col=1) # doctest: +ELLIPSIS
+    Figure(...)
 
     Example 6:
 
@@ -316,7 +327,8 @@ def make_subplots(
     ...                        b=[0.2, 0.3, 0.1],
     ...                        c=[0.7, 0.5, 0.8])],
     ...     rows=[1, 1, 2, 2],
-    ...     cols=[1, 2, 1, 2])
+    ...     cols=[1, 2, 1, 2]) # doctest: +ELLIPSIS
+    Figure(...)
     """
 
     import plotly.graph_objs as go
diff --git a/packages/python/plotly/plotly/utils.py b/packages/python/plotly/plotly/utils.py
index bf58ff756a1..0af0a49f710 100644
--- a/packages/python/plotly/plotly/utils.py
+++ b/packages/python/plotly/plotly/utils.py
@@ -149,9 +149,9 @@ def node_generator(node, path=()):
     Example:
 
         >>> for node, path in node_generator({'a': {'b': 5}}):
-        >>>     print node, path
+        ...     print(node, path)
         {'a': {'b': 5}} ()
-        {'b': 5} ('a', )
+        {'b': 5} ('a',)
 
     """
     if not isinstance(node, dict):
@@ -176,8 +176,8 @@ def get_by_path(obj, path):
 
         >>> figure = {'data': [{'x': [5]}]}
         >>> path = ('data', 0, 'x')
-        >>> get_by_path(figure, path)  # [5]
-
+        >>> get_by_path(figure, path)
+        [5]
     """
     for key in path:
         obj = obj[key]

From 08d7371ddc6d7a887e5c239e9affcbc72d65bc1c Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Mon, 25 Nov 2019 11:09:02 -0500
Subject: [PATCH 02/18] docstrings of figure factories

---
 .../python/plotly/plotly/basedatatypes.py     | 18 +++---
 .../plotly/figure_factory/_2d_density.py      |  3 +-
 .../figure_factory/_annotated_heatmap.py      |  2 +-
 .../plotly/plotly/figure_factory/_bullet.py   |  3 +-
 .../plotly/figure_factory/_candlestick.py     |  3 +-
 .../plotly/figure_factory/_dendrogram.py      |  4 +-
 .../plotly/plotly/figure_factory/_distplot.py | 12 +++-
 .../plotly/figure_factory/_facet_grid.py      | 56 ++++---------------
 .../plotly/plotly/figure_factory/_ohlc.py     |  3 +-
 .../plotly/figure_factory/_scatterplot.py     |  4 +-
 .../plotly/plotly/figure_factory/_table.py    | 32 +----------
 .../plotly/plotly/figure_factory/_violin.py   |  3 +-
 12 files changed, 51 insertions(+), 92 deletions(-)

diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py
index 6d24da3c015..cd551fc31c7 100644
--- a/packages/python/plotly/plotly/basedatatypes.py
+++ b/packages/python/plotly/plotly/basedatatypes.py
@@ -458,7 +458,7 @@ def update(self, dict1=None, overwrite=False, **kwargs):
         --------
         >>> import plotly.graph_objs as go
         >>> fig = go.Figure(data=[{'y': [1, 2, 3]}])
-        >>> fig.update(data=[{'y': [4, 5, 6]}]) #doctest: +ELLIPSIS
+        >>> fig.update(data=[{'y': [4, 5, 6]}]) # doctest: +ELLIPSIS
         Figure(...)
         >>> fig.to_plotly_json() # doctest: +SKIP
             {'data': [{'type': 'scatter',
@@ -469,7 +469,7 @@ def update(self, dict1=None, overwrite=False, **kwargs):
         >>> fig = go.Figure(layout={'xaxis':
         ...                         {'color': 'green',
         ...                          'range': [0, 1]}})
-        >>> fig.update({'layout': {'xaxis': {'color': 'pink'}}}) #doctest: +ELLIPSIS
+        >>> fig.update({'layout': {'xaxis': {'color': 'pink'}}}) # doctest: +ELLIPSIS
         Figure(...)
         >>> fig.to_plotly_json() # doctest: +SKIP
             {'data': [],
@@ -1590,18 +1590,18 @@ def add_trace(self, trace, row=None, col=None, secondary_y=None):
         Add two Scatter traces to a figure
 
         >>> fig = go.Figure()
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) #doctest: +ELLIPSIS
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) # doctest: +ELLIPSIS
         Figure(...)
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) #doctest: +ELLIPSIS
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2])) # doctest: +ELLIPSIS
         Figure(...)
 
 
         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) #doctest: +ELLIPSIS
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) # doctest: +ELLIPSIS
         Figure(...)
-        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1) #doctest: +ELLIPSIS
+        >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1) # doctest: +ELLIPSIS
         Figure(...)
         """
         # Make sure we have both row and col or neither
@@ -1670,7 +1670,7 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
 
         >>> 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])]) #doctest: +ELLIPSIS
+        ...                 go.Scatter(x=[1,2,3], y=[2,1,2])]) # doctest: +ELLIPSIS
         Figure(...)
 
         Add two Scatter traces to vertically stacked subplots
@@ -1678,7 +1678,7 @@ def add_traces(self, data, rows=None, cols=None, secondary_ys=None):
         >>> 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])],
-        ...                 rows=[1, 2], cols=[1, 1]) #doctest: +ELLIPSIS
+        ...                 rows=[1, 2], cols=[1, 1]) # doctest: +ELLIPSIS
         Figure(...)
         """
 
@@ -2166,7 +2166,7 @@ def _build_dispatch_plan(key_path_strs):
         >>> key_path_strs = ['xaxis.rangeselector.font.color',
         ...                  'xaxis.rangeselector.bgcolor']
 
-        >>> BaseFigure._build_dispatch_plan(key_path_strs) #doctest: +SKIP
+        >>> BaseFigure._build_dispatch_plan(key_path_strs) # doctest: +SKIP
             {(): {'xaxis',
                   ('xaxis', 'rangeselector'),
                   ('xaxis', 'rangeselector', 'bgcolor'),
diff --git a/packages/python/plotly/plotly/figure_factory/_2d_density.py b/packages/python/plotly/plotly/figure_factory/_2d_density.py
index e63b2af2e9b..9b8362be4d8 100644
--- a/packages/python/plotly/plotly/figure_factory/_2d_density.py
+++ b/packages/python/plotly/plotly/figure_factory/_2d_density.py
@@ -32,7 +32,8 @@ def create_2d_density(
     width=600,
 ):
     """
-    Returns figure for a 2D density plot
+    **This function is deprecated**, use instead
+    :func:`plotly.express.density_heatmap`.
 
     :param (list|array) x: x-axis data for plot generation
     :param (list|array) y: y-axis data for plot generation
diff --git a/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py b/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
index d158afe3171..9b5bf0a0b17 100644
--- a/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
+++ b/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
@@ -59,7 +59,7 @@ def create_annotated_heatmap(
     **kwargs
 ):
     """
-    BETA function that creates annotated heatmaps
+    Function that creates annotated heatmaps
 
     This function adds annotations to each cell of the heatmap.
 
diff --git a/packages/python/plotly/plotly/figure_factory/_bullet.py b/packages/python/plotly/plotly/figure_factory/_bullet.py
index 111e713a3a4..4bf0a33b061 100644
--- a/packages/python/plotly/plotly/figure_factory/_bullet.py
+++ b/packages/python/plotly/plotly/figure_factory/_bullet.py
@@ -198,7 +198,8 @@ def create_bullet(
     **layout_options
 ):
     """
-    Returns figure for bullet chart.
+    **This function is deprecated**, use instead the plotly.graph_objects trace
+    :class:`plotly.graph_objects.Indicator`.
 
     :param (pd.DataFrame | list | tuple) data: either a list/tuple of
         dictionaries or a pandas DataFrame.
diff --git a/packages/python/plotly/plotly/figure_factory/_candlestick.py b/packages/python/plotly/plotly/figure_factory/_candlestick.py
index 153b49f42ff..c8b3ac50f70 100644
--- a/packages/python/plotly/plotly/figure_factory/_candlestick.py
+++ b/packages/python/plotly/plotly/figure_factory/_candlestick.py
@@ -99,7 +99,8 @@ def make_decreasing_candle(open, high, low, close, dates, **kwargs):
 
 def create_candlestick(open, high, low, close, dates=None, direction="both", **kwargs):
     """
-    BETA function that creates a candlestick chart
+    **This function is deprecated**, use instead the plotly.graph_objects trace 
+    :class:`plotly.graph_objects.Candlestick`
 
     :param (list) open: opening values
     :param (list) high: high values
diff --git a/packages/python/plotly/plotly/figure_factory/_dendrogram.py b/packages/python/plotly/plotly/figure_factory/_dendrogram.py
index 2e1897835c8..380487e9a82 100644
--- a/packages/python/plotly/plotly/figure_factory/_dendrogram.py
+++ b/packages/python/plotly/plotly/figure_factory/_dendrogram.py
@@ -25,7 +25,9 @@ def create_dendrogram(
     color_threshold=None,
 ):
     """
-    BETA function that returns a dendrogram Plotly figure object.
+    Function that returns a dendrogram Plotly figure object.
+
+    See also https://dash.plot.ly/dash-bio/clustergram.
 
     :param (ndarray) X: Matrix of observations as array of arrays
     :param (str) orientation: 'top', 'right', 'bottom', or 'left'
diff --git a/packages/python/plotly/plotly/figure_factory/_distplot.py b/packages/python/plotly/plotly/figure_factory/_distplot.py
index 6c4ae79f1ef..997a7dc0166 100644
--- a/packages/python/plotly/plotly/figure_factory/_distplot.py
+++ b/packages/python/plotly/plotly/figure_factory/_distplot.py
@@ -62,7 +62,17 @@ def create_distplot(
     show_rug=True,
 ):
     """
-    BETA function that creates a distplot similar to seaborn.distplot
+    Function that creates a distplot similar to seaborn.distplot
+
+    **This function is deprecated**, use instead :mod:`plotly.express`
+    functions, for example
+
+    >>> import plotly.express as px
+    >>> tips = px.data.tips()
+    >>> fig = px.histogram(tips, x="total_bill", y="tip", color="sex", marginal="rug",
+    ...                    hover_data=tips.columns)
+    >>> fig.show()
+
 
     The distplot can be composed of all or any combination of the following
     3 components: (1) histogram, (2) curve: (a) kernel density estimation
diff --git a/packages/python/plotly/plotly/figure_factory/_facet_grid.py b/packages/python/plotly/plotly/figure_factory/_facet_grid.py
index 010df401982..61a7ddf7318 100644
--- a/packages/python/plotly/plotly/figure_factory/_facet_grid.py
+++ b/packages/python/plotly/plotly/figure_factory/_facet_grid.py
@@ -673,7 +673,18 @@ def create_facet_grid(
     **kwargs
 ):
     """
-    Returns figure for facet grid.
+    Returns figure for facet grid. This function is deprecated, since
+    plotly.express functions should be used instead, for example
+
+    >>> import plotly.express as px
+    >>> tips = px.data.tips()
+    >>> fig = px.scatter(tips, 
+    ...     x='total_bill',
+    ...     y='tip',
+    ...     facet_row='sex',
+    ...     facet_col='smoker',
+    ...     color='size')
+
 
     :param (pd.DataFrame) df: the dataframe of columns for the facet grid.
     :param (str) x: the name of the dataframe column for the x axis data.
@@ -766,50 +777,7 @@ def create_facet_grid(
     ... )
     >>> fig.show()
 
-    Example 4: Sequential Coloring
-
-    >>> import plotly.figure_factory as ff
-    >>> import pandas as pd
-    >>> tips = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/tips.csv')
-    >>> tips.size = tips.size.astype(str)
-
-    >>> fig = ff.create_facet_grid(
-    ...     tips,
-    ...     x='total_bill',
-    ...     y='tip',
-    ...     facet_row='sex',
-    ...     facet_col='smoker',
-    ...     color_name='size',
-    ...     colormap='Viridis',
-    ... )
-    >>> fig.show()
-
-    Example 5: Custom labels
 
-    >>> import plotly.figure_factory as ff
-    >>> import pandas as pd
-    >>> mtcars = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/mtcars.csv')
-    >>> fig = ff.create_facet_grid(
-    ...     mtcars,
-    ...     x='wt',
-    ...     y='mpg',
-    ...     facet_col='cyl',
-    ...     facet_col_labels={4: "$\\alpha$", 6: '$\\beta$', 8: '$\sqrt[y]{x}$'},
-    ... )
-    >>> fig.show()
-
-    Example 6: Other Trace Type
-
-    >>> import plotly.figure_factory as ff
-    >>> import pandas as pd
-    >>> mtcars = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/mtcars.csv')
-    >>> fig = ff.create_facet_grid(
-    ...     mtcars,
-    ...     x='wt',
-    ...     facet_col='cyl',
-    ...     trace_type='histogram',
-    ... )
-    >>> fig.show()
     """
     if not pd:
         raise ImportError("'pandas' must be installed for this figure_factory.")
diff --git a/packages/python/plotly/plotly/figure_factory/_ohlc.py b/packages/python/plotly/plotly/figure_factory/_ohlc.py
index ed3d647fbe8..a51c346385b 100644
--- a/packages/python/plotly/plotly/figure_factory/_ohlc.py
+++ b/packages/python/plotly/plotly/figure_factory/_ohlc.py
@@ -134,7 +134,8 @@ def make_decreasing_ohlc(open, high, low, close, dates, **kwargs):
 
 def create_ohlc(open, high, low, close, dates=None, direction="both", **kwargs):
     """
-    BETA function that creates an ohlc chart
+    **This function is deprecated**, use instead the plotly.graph_objects trace 
+    :class:`plotly.graph_objects.Ohlc`
 
     :param (list) open: opening values
     :param (list) high: high values
diff --git a/packages/python/plotly/plotly/figure_factory/_scatterplot.py b/packages/python/plotly/plotly/figure_factory/_scatterplot.py
index 9d606c1d7ac..d5852368cc9 100644
--- a/packages/python/plotly/plotly/figure_factory/_scatterplot.py
+++ b/packages/python/plotly/plotly/figure_factory/_scatterplot.py
@@ -854,7 +854,9 @@ def create_scatterplotmatrix(
     **kwargs
 ):
     """
-    Returns data for a scatterplot matrix.
+    Returns data for a scatterplot matrix. **This function is deprecated**,
+    use instead the plotly.graph_objects trace
+    :class:`plotly.graph_objects.Splom`.
 
     :param (array) df: array of the data with column headers
     :param (str) index: name of the index column in data array
diff --git a/packages/python/plotly/plotly/figure_factory/_table.py b/packages/python/plotly/plotly/figure_factory/_table.py
index 8e3087410d0..8ed8f30be85 100644
--- a/packages/python/plotly/plotly/figure_factory/_table.py
+++ b/packages/python/plotly/plotly/figure_factory/_table.py
@@ -36,7 +36,8 @@ def create_table(
     **kwargs
 ):
     """
-    BETA function that creates data tables
+    **This function is deprecated**, use instead the plotly.graph_objects trace 
+    :class:`plotly.graph_objects.Table`
 
     :param (pandas.Dataframe | list[list]) text: data for table.
     :param (str|list[list]) colorscale: Colorscale for table where the
@@ -69,35 +70,6 @@ def create_table(
 
     >>> table = create_table(text)
     >>> table.show()
-
-    Example 2: Table with Custom Coloring
-
-    >>> from plotly.figure_factory import create_table
-
-    >>> text = [['Country', 'Year', 'Population'],
-    ...         ['US', 2000, 282200000],
-    ...         ['Canada', 2000, 27790000],
-    ...         ['US', 2010, 309000000],
-    ...         ['Canada', 2010, 34000000]]
-
-    >>> table = create_table(text,
-    ...                      colorscale=[[0, '#000000'],
-    ...                                  [.5, '#80beff'],
-    ...                                  [1, '#cce5ff']],
-    ...                      font_colors=['#ffffff', '#000000',
-    ...                                 '#000000'])
-    >>> table.show()
-
-    Example 3: Simple Plotly Table with Pandas
-
-    >>> from plotly.figure_factory import create_table
-    >>> import pandas as pd
-
-    >>> df = pd.read_csv('http://www.stat.ubc.ca/~jenny/notOcto/STAT545A/examples/gapminder/data/gapminderDataFiveYear.txt', sep='\t')
-    >>> df_p = df[0:25]
-
-    >>> table_simple = create_table(df_p)
-    >>> table_simple.show()
     """
 
     # Avoiding mutables in the call signature
diff --git a/packages/python/plotly/plotly/figure_factory/_violin.py b/packages/python/plotly/plotly/figure_factory/_violin.py
index 7a48ccaeb75..a38e90fe6b1 100644
--- a/packages/python/plotly/plotly/figure_factory/_violin.py
+++ b/packages/python/plotly/plotly/figure_factory/_violin.py
@@ -451,7 +451,8 @@ def create_violin(
     title="Violin and Rug Plot",
 ):
     """
-    Returns figure for a violin plot
+    **This function is deprecated**, use instead the plotly.graph_objects trace
+    :class:`plotly.graph_objects.Violin`.
 
     :param (list|array) data: accepts either a list of numerical values,
         a list of dictionaries all with identical keys and at least one

From b0bdb4044d39d20970a1dc68d147e109d36b30cc Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 12:24:31 -0500
Subject: [PATCH 03/18] docstring formatting for deprecations

---
 packages/python/plotly/plotly/figure_factory/_2d_density.py  | 2 +-
 packages/python/plotly/plotly/figure_factory/_bullet.py      | 2 +-
 packages/python/plotly/plotly/figure_factory/_candlestick.py | 2 +-
 packages/python/plotly/plotly/figure_factory/_distplot.py    | 5 ++---
 packages/python/plotly/plotly/figure_factory/_facet_grid.py  | 2 +-
 packages/python/plotly/plotly/figure_factory/_gantt.py       | 1 +
 packages/python/plotly/plotly/figure_factory/_ohlc.py        | 2 +-
 packages/python/plotly/plotly/figure_factory/_scatterplot.py | 3 ++-
 packages/python/plotly/plotly/figure_factory/_table.py       | 2 +-
 packages/python/plotly/plotly/figure_factory/_violin.py      | 2 +-
 10 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/packages/python/plotly/plotly/figure_factory/_2d_density.py b/packages/python/plotly/plotly/figure_factory/_2d_density.py
index 9b8362be4d8..e6d7d7874d2 100644
--- a/packages/python/plotly/plotly/figure_factory/_2d_density.py
+++ b/packages/python/plotly/plotly/figure_factory/_2d_density.py
@@ -32,7 +32,7 @@ def create_2d_density(
     width=600,
 ):
     """
-    **This function is deprecated**, use instead
+    **deprecated**, use instead
     :func:`plotly.express.density_heatmap`.
 
     :param (list|array) x: x-axis data for plot generation
diff --git a/packages/python/plotly/plotly/figure_factory/_bullet.py b/packages/python/plotly/plotly/figure_factory/_bullet.py
index 4bf0a33b061..7d5a23ae2e4 100644
--- a/packages/python/plotly/plotly/figure_factory/_bullet.py
+++ b/packages/python/plotly/plotly/figure_factory/_bullet.py
@@ -198,7 +198,7 @@ def create_bullet(
     **layout_options
 ):
     """
-    **This function is deprecated**, use instead the plotly.graph_objects trace
+    **deprecated**, use instead the plotly.graph_objects trace
     :class:`plotly.graph_objects.Indicator`.
 
     :param (pd.DataFrame | list | tuple) data: either a list/tuple of
diff --git a/packages/python/plotly/plotly/figure_factory/_candlestick.py b/packages/python/plotly/plotly/figure_factory/_candlestick.py
index c8b3ac50f70..2ab76122530 100644
--- a/packages/python/plotly/plotly/figure_factory/_candlestick.py
+++ b/packages/python/plotly/plotly/figure_factory/_candlestick.py
@@ -99,7 +99,7 @@ def make_decreasing_candle(open, high, low, close, dates, **kwargs):
 
 def create_candlestick(open, high, low, close, dates=None, direction="both", **kwargs):
     """
-    **This function is deprecated**, use instead the plotly.graph_objects trace 
+    **deprecated**, use instead the plotly.graph_objects trace 
     :class:`plotly.graph_objects.Candlestick`
 
     :param (list) open: opening values
diff --git a/packages/python/plotly/plotly/figure_factory/_distplot.py b/packages/python/plotly/plotly/figure_factory/_distplot.py
index 997a7dc0166..52cd08b69ab 100644
--- a/packages/python/plotly/plotly/figure_factory/_distplot.py
+++ b/packages/python/plotly/plotly/figure_factory/_distplot.py
@@ -62,9 +62,8 @@ def create_distplot(
     show_rug=True,
 ):
     """
-    Function that creates a distplot similar to seaborn.distplot
-
-    **This function is deprecated**, use instead :mod:`plotly.express`
+    Function that creates a distplot similar to seaborn.distplot;
+    **this function is deprecated**, use instead :mod:`plotly.express`
     functions, for example
 
     >>> import plotly.express as px
diff --git a/packages/python/plotly/plotly/figure_factory/_facet_grid.py b/packages/python/plotly/plotly/figure_factory/_facet_grid.py
index 61a7ddf7318..9fc47879c22 100644
--- a/packages/python/plotly/plotly/figure_factory/_facet_grid.py
+++ b/packages/python/plotly/plotly/figure_factory/_facet_grid.py
@@ -673,7 +673,7 @@ def create_facet_grid(
     **kwargs
 ):
     """
-    Returns figure for facet grid. This function is deprecated, since
+    Returns figure for facet grid; **this function is deprecated**, since
     plotly.express functions should be used instead, for example
 
     >>> import plotly.express as px
diff --git a/packages/python/plotly/plotly/figure_factory/_gantt.py b/packages/python/plotly/plotly/figure_factory/_gantt.py
index f4ec5f58281..3d3f8f5cdd5 100644
--- a/packages/python/plotly/plotly/figure_factory/_gantt.py
+++ b/packages/python/plotly/plotly/figure_factory/_gantt.py
@@ -820,6 +820,7 @@ def create_gantt(
 ):
     """
     Returns figure for a gantt chart
+
     :param (array|list) df: input data for gantt chart. Must be either a
         a dataframe or a list. If dataframe, the columns must include
         'Task', 'Start' and 'Finish'. Other columns can be included and
diff --git a/packages/python/plotly/plotly/figure_factory/_ohlc.py b/packages/python/plotly/plotly/figure_factory/_ohlc.py
index a51c346385b..49ca1aa196a 100644
--- a/packages/python/plotly/plotly/figure_factory/_ohlc.py
+++ b/packages/python/plotly/plotly/figure_factory/_ohlc.py
@@ -134,7 +134,7 @@ def make_decreasing_ohlc(open, high, low, close, dates, **kwargs):
 
 def create_ohlc(open, high, low, close, dates=None, direction="both", **kwargs):
     """
-    **This function is deprecated**, use instead the plotly.graph_objects trace 
+    **deprecated**, use instead the plotly.graph_objects trace 
     :class:`plotly.graph_objects.Ohlc`
 
     :param (list) open: opening values
diff --git a/packages/python/plotly/plotly/figure_factory/_scatterplot.py b/packages/python/plotly/plotly/figure_factory/_scatterplot.py
index d5852368cc9..65164db0319 100644
--- a/packages/python/plotly/plotly/figure_factory/_scatterplot.py
+++ b/packages/python/plotly/plotly/figure_factory/_scatterplot.py
@@ -854,7 +854,8 @@ def create_scatterplotmatrix(
     **kwargs
 ):
     """
-    Returns data for a scatterplot matrix. **This function is deprecated**,
+    Returns data for a scatterplot matrix;
+    **deprecated**,
     use instead the plotly.graph_objects trace
     :class:`plotly.graph_objects.Splom`.
 
diff --git a/packages/python/plotly/plotly/figure_factory/_table.py b/packages/python/plotly/plotly/figure_factory/_table.py
index 8ed8f30be85..96dcbbfdab9 100644
--- a/packages/python/plotly/plotly/figure_factory/_table.py
+++ b/packages/python/plotly/plotly/figure_factory/_table.py
@@ -36,7 +36,7 @@ def create_table(
     **kwargs
 ):
     """
-    **This function is deprecated**, use instead the plotly.graph_objects trace 
+    **deprecated**, use instead the plotly.graph_objects trace 
     :class:`plotly.graph_objects.Table`
 
     :param (pandas.Dataframe | list[list]) text: data for table.
diff --git a/packages/python/plotly/plotly/figure_factory/_violin.py b/packages/python/plotly/plotly/figure_factory/_violin.py
index a38e90fe6b1..d7ac7a8f2a0 100644
--- a/packages/python/plotly/plotly/figure_factory/_violin.py
+++ b/packages/python/plotly/plotly/figure_factory/_violin.py
@@ -451,7 +451,7 @@ def create_violin(
     title="Violin and Rug Plot",
 ):
     """
-    **This function is deprecated**, use instead the plotly.graph_objects trace
+    **deprecated**, use instead the plotly.graph_objects trace
     :class:`plotly.graph_objects.Violin`.
 
     :param (list|array) data: accepts either a list of numerical values,

From dd712f95e4ff01316f54e43a825864e8898308f8 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 14:43:34 -0500
Subject: [PATCH 04/18] template + conftest

---
 packages/python/plotly/plotly/conftest.py     | 24 +++++++++++
 .../python/plotly/plotly/io/_templates.py     | 41 ++++++++-----------
 2 files changed, 41 insertions(+), 24 deletions(-)
 create mode 100644 packages/python/plotly/plotly/conftest.py

diff --git a/packages/python/plotly/plotly/conftest.py b/packages/python/plotly/plotly/conftest.py
new file mode 100644
index 00000000000..3669669e6a9
--- /dev/null
+++ b/packages/python/plotly/plotly/conftest.py
@@ -0,0 +1,24 @@
+import pytest
+import os
+
+
+def pytest_ignore_collect(path):
+    # Ignored files, most of them are raising a chart studio error
+    ignored_paths = [
+        "exploding_module.py",
+        "chunked_requests.py",
+        "v2.py",
+        "v1.py",
+        "presentation_objs.py",
+        "widgets.py",
+        "dashboard_objs.py",
+        "grid_objs.py",
+        "config.py",
+        "presentation_objs.py",
+        "session.py",
+        "utils.py",
+    ]
+    if os.path.basename(
+        path
+    ) in ignored_paths or "plotly/plotly/plotly/__init__.py" in str(path):
+        return True
diff --git a/packages/python/plotly/plotly/io/_templates.py b/packages/python/plotly/plotly/io/_templates.py
index b2e546a288e..f9f399a1b24 100644
--- a/packages/python/plotly/plotly/io/_templates.py
+++ b/packages/python/plotly/plotly/io/_templates.py
@@ -375,7 +375,8 @@ def to_templated(fig, skip=("title", "text")):
     Construct a figure with large courier text
 
     >>> fig = go.Figure(layout={'title': 'Figure Title',
-    ...                         'font': {'size': 20, 'family': 'Courier'}})
+    ...                         'font': {'size': 20, 'family': 'Courier'},
+    ...                         'template':"none"})
     >>> fig # doctest: +NORMALIZE_WHITESPACE
     Figure({
         'data': [],
@@ -387,25 +388,24 @@ def to_templated(fig, skip=("title", "text")):
     been moved into the template property.
 
     >>> templated_fig = pio.to_templated(fig)
+    >>> templated_fig.layout.template
+    layout.Template({
+        'data': {}, 'layout': {'font': {'family': 'Courier', 'size': 20}}
+    })
     >>> templated_fig
     Figure({
-        'data': [],
-        'layout': {'title': 'Figure Title',
-                   'template': {'layout': {'font': {'family': 'Courier',
-                                                    'size': 20}}}}
+        'data': [], 'layout': {'template': '...', 'title': {'text': 'Figure Title'}}
     })
 
+
     Next create a new figure with this template
 
     >>> fig2 = go.Figure(layout={
     ...     'title': 'Figure 2 Title',
     ...     'template': templated_fig.layout.template})
-    >>> fig2
-    Figure({
-        'data': [],
-        'layout': {'title': 'Figure 2 Title',
-                   'template': {'layout': {'font': {'family': 'Courier',
-                                                    'size': 20}}}}
+    >>> fig2.layout.template
+    layout.Template({
+        'layout': {'font': {'family': 'Courier', 'size': 20}}
     })
 
     The default font in fig2 will now be size 20 Courier.
@@ -418,23 +418,16 @@ def to_templated(fig, skip=("title", "text")):
 
     >>> go.Figure(layout={
     ...     'title': 'Figure 3 Title',
-    ...     'template': 'large_courier'})
-    Figure({
-        'data': [],
-        'layout': {'title': 'Figure 3 Title',
-                   'template': {'layout': {'font': {'family': 'Courier',
-                                                    'size': 20}}}}
-    })
+    ...     'template': 'large_courier'}) # doctest: +ELLIPSIS
+    Figure(...)
 
     Finally, set this as the default template to be applied to all new figures
 
     >>> pio.templates.default = 'large_courier'
-    >>> go.Figure(layout={'title': 'Figure 4 Title'})
-    Figure({
-        'data': [],
-        'layout': {'title': 'Figure 4 Title',
-                   'template': {'layout': {'font': {'family': 'Courier',
-                                                    'size': 20}}}}
+    >>> fig = go.Figure(layout={'title': 'Figure 4 Title'})
+    >>> fig.layout.template
+    layout.Template({
+        'layout': {'font': {'family': 'Courier', 'size': 20}}
     })
 
     Returns

From 059548e846c1e2493fb0d6fab44501f379563643 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 14:46:57 -0500
Subject: [PATCH 05/18] added doctest job in tox.ini

---
 packages/python/plotly/tox.ini | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/python/plotly/tox.ini b/packages/python/plotly/tox.ini
index df41b7e1df1..2fe078b27e6 100644
--- a/packages/python/plotly/tox.ini
+++ b/packages/python/plotly/tox.ini
@@ -147,3 +147,4 @@ commands=
     nosetests {posargs} -x plotly/tests/test_optional
     pytest _plotly_utils/tests/
     pytest plotly/tests/test_io
+    pytest --doctest-modules plotly/

From b5ab4fc557a969e94de4ea58aacc1047071a6739 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 14:51:05 -0500
Subject: [PATCH 06/18] bug fix in conftest

---
 packages/python/plotly/plotly/conftest.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/python/plotly/plotly/conftest.py b/packages/python/plotly/plotly/conftest.py
index 3669669e6a9..b4605621813 100644
--- a/packages/python/plotly/plotly/conftest.py
+++ b/packages/python/plotly/plotly/conftest.py
@@ -19,6 +19,6 @@ def pytest_ignore_collect(path):
         "utils.py",
     ]
     if os.path.basename(
-        path
+        str(path)
     ) in ignored_paths or "plotly/plotly/plotly/__init__.py" in str(path):
         return True

From eb9d4ab719a8f91a3a60b3e9384089437a9b2375 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 14:57:55 -0500
Subject: [PATCH 07/18] moved doctest to python 3.6

---
 packages/python/plotly/tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/python/plotly/tox.ini b/packages/python/plotly/tox.ini
index 2fe078b27e6..5a4670a546e 100644
--- a/packages/python/plotly/tox.ini
+++ b/packages/python/plotly/tox.ini
@@ -138,6 +138,7 @@ commands=
     nosetests {posargs} -x plotly/tests/test_optional
     pytest _plotly_utils/tests/
     pytest plotly/tests/test_io
+    pytest --doctest-modules plotly/
 
 [testenv:py37-optional]
 basepython={env:PLOTLY_TOX_PYTHON_37:}
@@ -147,4 +148,3 @@ commands=
     nosetests {posargs} -x plotly/tests/test_optional
     pytest _plotly_utils/tests/
     pytest plotly/tests/test_io
-    pytest --doctest-modules plotly/

From 2a68a1e63c035844c20aec880e5c488008443d6d Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 15:20:55 -0500
Subject: [PATCH 08/18] deps in test

---
 packages/python/plotly/tox.ini | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/python/plotly/tox.ini b/packages/python/plotly/tox.ini
index 5a4670a546e..81210f979e2 100644
--- a/packages/python/plotly/tox.ini
+++ b/packages/python/plotly/tox.ini
@@ -75,6 +75,7 @@ deps=
     optional: matplotlib==2.2.3
     optional: xarray==0.10.9
     optional: scikit-image==0.14.4
+    optional: psutil==5.6.7
 
 ; CORE ENVIRONMENTS
 [testenv:py27-core]
@@ -134,11 +135,11 @@ commands=
 basepython={env:PLOTLY_TOX_PYTHON_36:}
 commands=
     python --version
+    pytest --doctest-modules plotly/
     nosetests {posargs} -x plotly/tests/test_core
     nosetests {posargs} -x plotly/tests/test_optional
     pytest _plotly_utils/tests/
     pytest plotly/tests/test_io
-    pytest --doctest-modules plotly/
 
 [testenv:py37-optional]
 basepython={env:PLOTLY_TOX_PYTHON_37:}

From 1156645f35eac6f41ffd705fe73af2de1f28735b Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 15:25:46 -0500
Subject: [PATCH 09/18] added init in test dirs

---
 .../plotly/plotly/tests/test_core/test_subplots/__init__.py       | 0
 .../plotly/plotly/tests/test_optional/test_subplots/__init__.py   | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 packages/python/plotly/plotly/tests/test_core/test_subplots/__init__.py
 create mode 100644 packages/python/plotly/plotly/tests/test_optional/test_subplots/__init__.py

diff --git a/packages/python/plotly/plotly/tests/test_core/test_subplots/__init__.py b/packages/python/plotly/plotly/tests/test_core/test_subplots/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/packages/python/plotly/plotly/tests/test_optional/test_subplots/__init__.py b/packages/python/plotly/plotly/tests/test_optional/test_subplots/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d

From 427cd81f3f51d13467ef7868a1e4f4e238d72dc3 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 15:35:27 -0500
Subject: [PATCH 10/18] moved doctest to ci with orca

---
 .circleci/config.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 25583c16e04..22508bee047 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -325,6 +325,7 @@ jobs:
           command: |
             . /home/circleci/miniconda/etc/profile.d/conda.sh
             conda activate circle_optional
+            pytest --doctest-modules ackages/python/plotly/plotly
             pytest --disable-warnings packages/python/plotly/plotly/tests/test_core
             pytest packages/python/plotly/plotly/tests/test_orca
 

From 341b65810047377f7289df68bb2b9eeebac56138 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Wed, 27 Nov 2019 15:39:36 -0500
Subject: [PATCH 11/18] typo

---
 .circleci/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 22508bee047..f1b465b018e 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -325,7 +325,7 @@ jobs:
           command: |
             . /home/circleci/miniconda/etc/profile.d/conda.sh
             conda activate circle_optional
-            pytest --doctest-modules ackages/python/plotly/plotly
+            pytest --doctest-modules packages/python/plotly/plotly
             pytest --disable-warnings packages/python/plotly/plotly/tests/test_core
             pytest packages/python/plotly/plotly/tests/test_orca
 

From 18e039eb15b71719574d3ffbc46ddf99aaf1a3a8 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 14:05:25 -0500
Subject: [PATCH 12/18] more deps for CI

---
 .circleci/create_conda_optional_env.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/create_conda_optional_env.sh b/.circleci/create_conda_optional_env.sh
index 3cbbc63966a..ebd907688a5 100755
--- a/.circleci/create_conda_optional_env.sh
+++ b/.circleci/create_conda_optional_env.sh
@@ -16,7 +16,7 @@ if [ ! -d $HOME/miniconda/envs/circle_optional ]; then
     # Create environment
     # PYTHON_VERSION=3.6
     $HOME/miniconda/bin/conda create -n circle_optional --yes python=$PYTHON_VERSION \
-requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython
+requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets
 
     # Install orca into environment
     $HOME/miniconda/bin/conda install --yes -n circle_optional -c plotly plotly-orca

From 4e001f6efc0948bd2273c72cf617497a82614c78 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 14:28:38 -0500
Subject: [PATCH 13/18] doctest only in pytest command

---
 .circleci/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index f1b465b018e..75112be366d 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -325,7 +325,7 @@ jobs:
           command: |
             . /home/circleci/miniconda/etc/profile.d/conda.sh
             conda activate circle_optional
-            pytest --doctest-modules packages/python/plotly/plotly
+            pytest --doctest-modules --ignore packages/python/plotly/plotly/tests  packages/python/plotly/plotly 
             pytest --disable-warnings packages/python/plotly/plotly/tests/test_core
             pytest packages/python/plotly/plotly/tests/test_orca
 

From f6ddf2e4774c34d007555b7cdd9cd991d763fc38 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 14:34:30 -0500
Subject: [PATCH 14/18] ignore matplotlylib

---
 .circleci/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 75112be366d..4e0788a69e8 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -325,7 +325,7 @@ jobs:
           command: |
             . /home/circleci/miniconda/etc/profile.d/conda.sh
             conda activate circle_optional
-            pytest --doctest-modules --ignore packages/python/plotly/plotly/tests  packages/python/plotly/plotly 
+            pytest --doctest-modules --ignore packages/python/plotly/plotly/tests --ignore packages/python/plotly/plotly/matplotlylib/mplexporter/tests packages/python/plotly/plotly 
             pytest --disable-warnings packages/python/plotly/plotly/tests/test_core
             pytest packages/python/plotly/plotly/tests/test_orca
 

From 1dd8a7838fe19270ccc5f97707e873e28ab513f4 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 14:58:46 -0500
Subject: [PATCH 15/18] test fixes

---
 packages/python/plotly/plotly/conftest.py | 6 +++---
 packages/python/plotly/tox.ini            | 1 -
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/packages/python/plotly/plotly/conftest.py b/packages/python/plotly/plotly/conftest.py
index b4605621813..9ab4927ef7a 100644
--- a/packages/python/plotly/plotly/conftest.py
+++ b/packages/python/plotly/plotly/conftest.py
@@ -16,9 +16,9 @@ def pytest_ignore_collect(path):
         "config.py",
         "presentation_objs.py",
         "session.py",
-        "utils.py",
     ]
-    if os.path.basename(
+    if (os.path.basename(
         str(path)
-    ) in ignored_paths or "plotly/plotly/plotly/__init__.py" in str(path):
+    ) in ignored_paths or "plotly/plotly/plotly/__init__.py" in str(path)
+    or "plotly/api/utils.py" in str(path)):
         return True
diff --git a/packages/python/plotly/tox.ini b/packages/python/plotly/tox.ini
index 81210f979e2..0e5f1816971 100644
--- a/packages/python/plotly/tox.ini
+++ b/packages/python/plotly/tox.ini
@@ -135,7 +135,6 @@ commands=
 basepython={env:PLOTLY_TOX_PYTHON_36:}
 commands=
     python --version
-    pytest --doctest-modules plotly/
     nosetests {posargs} -x plotly/tests/test_core
     nosetests {posargs} -x plotly/tests/test_optional
     pytest _plotly_utils/tests/

From 03f5003b4e23ee68d5e399db3f7b7c8e7e096366 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 15:01:00 -0500
Subject: [PATCH 16/18] black

---
 packages/python/plotly/plotly/conftest.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/python/plotly/plotly/conftest.py b/packages/python/plotly/plotly/conftest.py
index 9ab4927ef7a..3e7bed965e6 100644
--- a/packages/python/plotly/plotly/conftest.py
+++ b/packages/python/plotly/plotly/conftest.py
@@ -17,8 +17,9 @@ def pytest_ignore_collect(path):
         "presentation_objs.py",
         "session.py",
     ]
-    if (os.path.basename(
-        str(path)
-    ) in ignored_paths or "plotly/plotly/plotly/__init__.py" in str(path)
-    or "plotly/api/utils.py" in str(path)):
+    if (
+        os.path.basename(str(path)) in ignored_paths
+        or "plotly/plotly/plotly/__init__.py" in str(path)
+        or "plotly/api/utils.py" in str(path)
+    ):
         return True

From 763ed9348faa527e9f49a8dbca4aa1b6e1863dd3 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 15:13:11 -0500
Subject: [PATCH 17/18] reverted change in tox.ini

---
 packages/python/plotly/tox.ini | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/python/plotly/tox.ini b/packages/python/plotly/tox.ini
index 0e5f1816971..df41b7e1df1 100644
--- a/packages/python/plotly/tox.ini
+++ b/packages/python/plotly/tox.ini
@@ -75,7 +75,6 @@ deps=
     optional: matplotlib==2.2.3
     optional: xarray==0.10.9
     optional: scikit-image==0.14.4
-    optional: psutil==5.6.7
 
 ; CORE ENVIRONMENTS
 [testenv:py27-core]

From fc2c4b8d0a88e138ad654ea06b793d2eb9246497 Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emma@plot.ly>
Date: Thu, 28 Nov 2019 17:15:17 -0500
Subject: [PATCH 18/18] reverted changes to table ff

---
 .../plotly/plotly/figure_factory/_table.py    | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/packages/python/plotly/plotly/figure_factory/_table.py b/packages/python/plotly/plotly/figure_factory/_table.py
index 96dcbbfdab9..c0eec1fb2bd 100644
--- a/packages/python/plotly/plotly/figure_factory/_table.py
+++ b/packages/python/plotly/plotly/figure_factory/_table.py
@@ -36,7 +36,9 @@ def create_table(
     **kwargs
 ):
     """
-    **deprecated**, use instead the plotly.graph_objects trace 
+    Function that creates data tables.
+
+    See also the plotly.graph_objects trace
     :class:`plotly.graph_objects.Table`
 
     :param (pandas.Dataframe | list[list]) text: data for table.
@@ -70,6 +72,32 @@ def create_table(
 
     >>> table = create_table(text)
     >>> table.show()
+
+    Example 2: Table with Custom Coloring
+
+    >>> from plotly.figure_factory import create_table
+    >>> text = [['Country', 'Year', 'Population'],
+    ...         ['US', 2000, 282200000],
+    ...         ['Canada', 2000, 27790000],
+    ...         ['US', 2010, 309000000],
+    ...         ['Canada', 2010, 34000000]]
+    >>> table = create_table(text,
+    ...                      colorscale=[[0, '#000000'],
+    ...                                  [.5, '#80beff'],
+    ...                                  [1, '#cce5ff']],
+    ...                      font_colors=['#ffffff', '#000000',
+    ...                                 '#000000'])
+    >>> table.show()
+
+    Example 3: Simple Plotly Table with Pandas
+
+    >>> from plotly.figure_factory import create_table
+    >>> import pandas as pd
+    >>> df = pd.read_csv('http://www.stat.ubc.ca/~jenny/notOcto/STAT545A/examples/gapminder/data/gapminderDataFiveYear.txt', sep='\t')
+    >>> df_p = df[0:25]
+    >>> table_simple = create_table(df_p)
+    >>> table_simple.show()
+
     """
 
     # Avoiding mutables in the call signature