From 899af8e55a932fba53cb25867b1335728e49804a Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sat, 27 Jun 2020 12:30:19 +0200 Subject: [PATCH] Reorganize colorbar docstrings. - Figure.colorbar and pyplot.colorbar can use the docstring (no need to restate the signatures, IPython/pydoc/sphinx does that for you). - Deprecate some docstrings that exist as globals at the module level. - Clarify what happens when `cax` and `ax` are both given (we can always emit a warning and deprecate that behavior later). --- doc/api/api_changes_3.4/deprecations.rst | 5 +++++ lib/matplotlib/colorbar.py | 28 +++++++++--------------- lib/matplotlib/figure.py | 7 +----- lib/matplotlib/pyplot.py | 2 +- 4 files changed, 17 insertions(+), 25 deletions(-) diff --git a/doc/api/api_changes_3.4/deprecations.rst b/doc/api/api_changes_3.4/deprecations.rst index d72501b76f7f..3bf67737923b 100644 --- a/doc/api/api_changes_3.4/deprecations.rst +++ b/doc/api/api_changes_3.4/deprecations.rst @@ -4,3 +4,8 @@ Deprecations ``dpi_cor`` property of `.FancyArrowPatch` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This parameter is considered internal and deprecated. + +Colorbar docstrings +~~~~~~~~~~~~~~~~~~~ +The following globals in :mod:`matplotlib.colorbar` are deprecated: +``colorbar_doc``, ``colormap_kw_doc``, ``make_axes_kw_doc``. diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py index f231c1a3d306..e8ef4e1f9853 100644 --- a/lib/matplotlib/colorbar.py +++ b/lib/matplotlib/colorbar.py @@ -84,9 +84,8 @@ axes' anchor will be unchanged. Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal. """ -make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc -colormap_kw_doc = """ +_colormap_kw_doc = """ ============ ==================================================== Property Description @@ -149,18 +148,9 @@ """ -colorbar_doc = """ - +docstring.interpd.update(colorbar_doc=""" Add a colorbar to a plot. -Function signatures for the :mod:`~matplotlib.pyplot` interface; all -but the first are also method signatures for the `~.Figure.colorbar` method:: - - colorbar(**kwargs) - colorbar(mappable, **kwargs) - colorbar(mappable, cax=cax, **kwargs) - colorbar(mappable, ax=ax, **kwargs) - Parameters ---------- mappable @@ -179,9 +169,8 @@ Axes into which the colorbar will be drawn. ax : `~matplotlib.axes.Axes`, list of Axes, optional - Parent axes from which space for a new colorbar axes will be stolen. - If a list of axes is given they will all be resized to make room for the - colorbar axes. + One or more parent axes from which space for a new colorbar axes will be + stolen, if *cax* is None. This has no effect if *cax* is set. use_gridspec : bool, optional If *cax* is ``None``, a new *cax* is created as an instance of Axes. If @@ -198,6 +187,7 @@ Additional keyword arguments are of two kinds: axes properties: +%s %s colorbar properties: %s @@ -225,10 +215,12 @@ However this has negative consequences in other circumstances, e.g. with semi-transparent images (alpha < 1) and colorbar extensions; therefore, this workaround is not used by default (see issue #1188). +""" % (_make_axes_param_doc, _make_axes_other_param_doc, _colormap_kw_doc)) -""" % (make_axes_kw_doc, colormap_kw_doc) - -docstring.interpd.update(colorbar_doc=colorbar_doc) +# Deprecated since 3.4. +colorbar_doc = docstring.interpd.params["colorbar_doc"] +colormap_kw_doc = _colormap_kw_doc +make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc def _set_ticks_on_axis_warn(*args, **kw): diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index ce8e71f54a53..7c740ff39abf 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2315,12 +2315,7 @@ def savefig(self, fname, *, transparent=None, **kwargs): @docstring.dedent_interpd def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw): - """ - Create a colorbar for a ScalarMappable instance, *mappable*. - - Documentation for the pyplot thin wrapper: - %(colorbar_doc)s - """ + """%(colorbar_doc)s""" if ax is None: ax = self.gca() diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index a4765d277c01..8d7b656106d1 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -2172,6 +2172,7 @@ def _setup_pyplot_info_docstrings(): ## Plotting part 1: manually generated functions and wrappers ## +@_copy_docstring_and_deprecators(Figure.colorbar) def colorbar(mappable=None, cax=None, ax=None, **kw): if mappable is None: mappable = gci() @@ -2184,7 +2185,6 @@ def colorbar(mappable=None, cax=None, ax=None, **kw): ax = gca() ret = gcf().colorbar(mappable, cax=cax, ax=ax, **kw) return ret -colorbar.__doc__ = matplotlib.colorbar.colorbar_doc def clim(vmin=None, vmax=None):