doctest package, with some docstrings modifications (plotly#1921)

* first round of changes towards doctesting

* docstrings of figure factories

* docstring formatting for deprecations

* template + conftest

* added doctest job in tox.ini

* bug fix in conftest

* moved doctest to python 3.6

* deps in test

* added init in test dirs

* moved doctest to ci with orca

* typo

* more deps for CI

* doctest only in pytest command

* ignore matplotlylib

* test fixes

* black

* reverted change in tox.ini

* reverted changes to table ff

Author: emmanuelle

.circleci/config.yml

@@ -325,6 +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 --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
 

.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

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,13 +4585,15 @@ def on_hover(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
         >>> def hover_fn(trace, points, state):
         ...     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,13 +4647,15 @@ def on_unhover(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
         >>> def unhover_fn(trace, points, state):
         ...     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,13 +4709,15 @@ def on_click(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points, InputDeviceState
         >>> points, state = Points(), InputDeviceState()
 
         >>> def click_fn(trace, points, state):
         ...     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,13 +4770,15 @@ def on_selection(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
         >>> def selection_fn(trace, points, selector):
         ...     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,13 +4838,15 @@ def on_deselect(self, callback, append=False):
         Examples
         --------
 
+        >>> import plotly.graph_objects as go
         >>> from plotly.callbacks import Points
         >>> points = Points()
 
         >>> def deselect_fn(trace, points):
         ...     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,

packages/python/plotly/plotly/conftest.py

@@ -0,0 +1,25 @@
+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",
+    ]
+    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

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
+    **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
@@ -56,8 +57,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 +66,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 +87,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

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.
 
@@ -94,7 +94,6 @@ def create_annotated_heatmap(
 
     >>> fig = ff.create_annotated_heatmap(z)
     >>> fig.show()
-    ```
     """
 
     # Avoiding mutables in the call signature

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

@@ -198,7 +198,8 @@ def create_bullet(
     **layout_options
 ):
     """
-    Returns figure for bullet chart.
+    **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.