Adding documentation and improving comments, based on Jeff review

Author: Marc Garcia

doc/source/development/extending.rst

@@ -416,3 +416,30 @@ Below is an example to define two original properties, "internal_cache" as a tem
    # properties defined in _metadata are retained
    >>> df[['A', 'B']].added_property
    property
+
+.. _extending.plotting-backends:
+
+Plotting backends
+-----------------
+
+Starting in 0.25 pandas can be extended with third-party plotting backends. The
+main idea is letting users select a plotting backend different than the provided
+one based on Matplotlib. For example:
+
+.. code-block:: python
+
+    >>> pd.set_option('plotting.backend', 'backend.module')
+    >>> pd.Series([1, 2, 3]).plot()
+
+This would be more or less equivalent to:
+
+.. code-block:: python
+
+    >>> import backend.module
+    >>> backend.module.plot(pd.Series([1, 2, 3]))
+
+The backend module can then use other visualization tools (Bokeh, Altair,...)
+to generate the plots.
+
+More information on how to implement a third-party plotting backend can be found at
+https://github.com/pandas-dev/pandas/blob/master/pandas/plotting/__init__.py#L1.

pandas/plotting/__init__.py

@@ -1,5 +1,60 @@
 """
-Plotting public API
+Plotting public API.
+
+Authors of third-party plotting backends should implement a module with a
+public ``plot(data, kind, **kwargs)``. The parameter `data` will contain
+the data structure and can be a `Series` or a `DataFrame`. For example,
+for ``df.plot()`` the parameter `data` will contain the DataFrame `df`.
+In some cases, the data structure is transformed before being sent to
+the backend (see PlotAccessor.__call__ in pandas/plotting/_core.py for
+the exact transformations).
+
+The parameter `kind` will be one of:
+
+- line
+- bar
+- barh
+- box
+- hist
+- kde
+- area
+- pie
+- scatter
+- hexbin
+
+See the pandas API reference for documentation on each kind of plot.
+
+Any other keyword argument is currently assumed to be backend specific,
+but some parameters may be unified and added to the signature in the
+future (e.g. `title` which should be useful for any backend).
+
+Currently, all the Matplotlib functions in pandas are accessed through
+the selected backend. For example, `pandas.plotting.boxplot` (equivalent
+to `DataFrame.boxplot`) is also accessed in the selected backend. This
+is expected to change, and the exact API is under discussion. But with
+the current version, backends are expected to implement the next functions:
+
+- plot (describe above, used for `Series.plot` and `DataFrame.plot`)
+- hist_series and hist_frame (for `Series.hist` and `DataFrame.hist`)
+- boxplot (`pandas.plotting.boxplot(df)` equivalent to `DataFrame.boxplot`)
+- boxplot_frame and boxplot_frame_groupby
+- tsplot (deprecated)
+- register and deregister (register converters for the tick formats)
+- Plots not called as `Series` and `DataFrame` methods:
+  - table
+  - andrews_curves
+  - autocorrelation_plot
+  - bootstrap_plot
+  - lag_plot
+  - parallel_coordinates
+  - radviz
+  - scatter_matrix
+
+Use the code in pandas/plotting/_matplotib.py and
+https://github.com/pyviz/hvplot as a reference on how to write a backend.
+
+For the discussion about the API see
+https://github.com/pandas-dev/pandas/issues/26747.
 """
 from pandas.plotting._core import (
     PlotAccessor, boxplot, boxplot_frame, boxplot_frame_groupby, hist_frame,
@@ -10,9 +65,9 @@
     parallel_coordinates, plot_params, radviz,
     register as register_matplotlib_converters, scatter_matrix, table)
 
-__all__ = ['boxplot', 'boxplot_frame', 'boxplot_frame_groupby', 'hist_frame',
-           'hist_series', 'PlotAccessor',
-           'scatter_matrix', 'radviz', 'andrews_curves', 'bootstrap_plot',
-           'parallel_coordinates', 'lag_plot', 'autocorrelation_plot',
-           'table', 'plot_params', 'register_matplotlib_converters',
+__all__ = ['PlotAccessor', 'boxplot', 'boxplot_frame', 'boxplot_frame_groupby',
+           'hist_frame', 'hist_series', 'scatter_matrix', 'radviz',
+           'andrews_curves', 'bootstrap_plot', 'parallel_coordinates',
+           'lag_plot', 'autocorrelation_plot', 'table', 'plot_params',
+           'register_matplotlib_converters',
            'deregister_matplotlib_converters']

pandas/plotting/_core.py

@@ -402,11 +402,6 @@ class PlotAccessor(PandasObject):
     Make plots of Series or DataFrame using the backend specified by the
     option ``plotting.backend``. By default, matplotlib is used.
 
-    *New in version 0.17.0:* Each plot kind has a corresponding method on
-    the Series or DataFrame accessor, for example:
-    ``Series.plot(kind='line')`` is equivalent to
-    ``Series.plot.line()``.
-
     Parameters
     ----------
     data : Series or DataFrame
@@ -517,13 +512,11 @@ def __init__(self, data):
     @staticmethod
     def _get_call_args(data, args, kwargs):
         """
-        We used to have different accessors for Series and DataFrame. Their
-        signatures were different:
-
-        - SeriesPlotMethods.__call__(kind, ..., **kwargs)
-        - DataFramePlotMethods.__call__(x, y, kind, ..., **kwargs)
-
-        This function makes this unified `__call__` method compatible with both
+        This function makes calls to this accessor `__call__` method compatible
+        with the previous `SeriesPlotMethods.__call__` and
+        `DataFramePlotMethods.__call__`. Those had slightly different
+        signatures, since `DataFramePlotMethods` accepted `x` and `y`
+        parameters.
         """
         if args and isinstance(data, ABCSeries):
             # TODO raise warning here, positional arguments shouldn't be
@@ -573,6 +566,9 @@ def __call__(self, *args, **kwargs):
             raise ValueError('{} is not a valid plot kind'.format(kind))
 
         plot_backend = _get_plot_backend()
+        # The original data structured can be transformed before passed to the
+        # backend. For example, for DataFrame is common to set the index as the
+        # `x` parameter, and return a Series with the parameter `y` as values.
         data = self._parent.copy()
 
         if isinstance(data, pandas.core.dtypes.generic.ABCSeries):