diff --git a/doc/api/next_api_changes/behavior/18440-AL.rst b/doc/api/next_api_changes/behavior/18440-AL.rst new file mode 100644 index 000000000000..8b9447c969ab --- /dev/null +++ b/doc/api/next_api_changes/behavior/18440-AL.rst @@ -0,0 +1,2 @@ +docstring.Substitution now always dedents docstrings before string interpolation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 8ab63b920b96..7d3c50c6a69a 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -104,7 +104,7 @@ # cbook must import matplotlib only within function # definitions, so it is safe to import from it here. -from . import cbook, rcsetup +from . import cbook, docstring, rcsetup from matplotlib.cbook import MatplotlibDeprecationWarning, sanitize_sequence from matplotlib.cbook import mplDeprecation # deprecated from matplotlib.rcsetup import validate_backend, cycler @@ -635,6 +635,7 @@ def gen_candidates(): _all_deprecated = {*_deprecated_map, *_deprecated_ignore_map} +@docstring.Substitution("\n".join(map("- {}".format, rcsetup._validators))) class RcParams(MutableMapping, dict): """ A dictionary object including validation. @@ -642,6 +643,10 @@ class RcParams(MutableMapping, dict): Validating functions are defined and associated with rc parameters in :mod:`matplotlib.rcsetup`. + The list of rcParams is: + + %s + See Also -------- :ref:`customizing-with-matplotlibrc-files` diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py index 3c60e4596d6a..80e0cab447ba 100644 --- a/lib/matplotlib/colorbar.py +++ b/lib/matplotlib/colorbar.py @@ -33,6 +33,7 @@ import copy import logging +import textwrap import numpy as np @@ -53,35 +54,34 @@ _log = logging.getLogger(__name__) _make_axes_param_doc = """ - location : None or {'left', 'right', 'top', 'bottom'} - The location, relative to the parent axes, where the colorbar axes - is created. It also determines the *orientation* of the colorbar - (colorbars on the left and right are vertical, colorbars at the top - and bottom are horizontal). If None, the location will come from the - *orientation* if it is set (vertical colorbars on the right, horizontal - ones at the bottom), or default to 'right' if *orientation* is unset. - orientation : None or {'vertical', 'horizontal'} - The orientation of the colorbar. It is preferrable to set the - *location* of the colorbar, as that also determines the *orientation*; - passing incompatible values for *location* and *orientation* raises an - exception. - fraction : float, default: 0.15 - Fraction of original axes to use for colorbar. - shrink : float, default: 1.0 - Fraction by which to multiply the size of the colorbar. - aspect : float, default: 20 - Ratio of long to short dimensions. +location : None or {'left', 'right', 'top', 'bottom'} + The location, relative to the parent axes, where the colorbar axes + is created. It also determines the *orientation* of the colorbar + (colorbars on the left and right are vertical, colorbars at the top + and bottom are horizontal). If None, the location will come from the + *orientation* if it is set (vertical colorbars on the right, horizontal + ones at the bottom), or default to 'right' if *orientation* is unset. +orientation : None or {'vertical', 'horizontal'} + The orientation of the colorbar. It is preferrable to set the *location* + of the colorbar, as that also determines the *orientation*; passing + incompatible values for *location* and *orientation* raises an exception. +fraction : float, default: 0.15 + Fraction of original axes to use for colorbar. +shrink : float, default: 1.0 + Fraction by which to multiply the size of the colorbar. +aspect : float, default: 20 + Ratio of long to short dimensions. """ _make_axes_other_param_doc = """ - pad : float, default: 0.05 if vertical, 0.15 if horizontal - Fraction of original axes between colorbar and new image axes. - anchor : (float, float), optional - The anchor point of the colorbar axes. - Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal. - panchor : (float, float), or *False*, optional - The anchor point of the colorbar parent axes. If *False*, the parent - axes' anchor will be unchanged. - Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal. +pad : float, default: 0.05 if vertical, 0.15 if horizontal + Fraction of original axes between colorbar and new image axes. +anchor : (float, float), optional + The anchor point of the colorbar axes. + Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal. +panchor : (float, float), or *False*, optional + The anchor point of the colorbar parent axes. If *False*, the parent + axes' anchor will be unchanged. + Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal. """ _colormap_kw_doc = """ @@ -214,7 +214,9 @@ 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)) +""" % (textwrap.indent(_make_axes_param_doc, " "), + textwrap.indent(_make_axes_other_param_doc, " "), + _colormap_kw_doc)) # Deprecated since 3.4. colorbar_doc = docstring.interpd.params["colorbar_doc"] diff --git a/lib/matplotlib/docstring.py b/lib/matplotlib/docstring.py index 4fb2d59d326c..a30e2ca33824 100644 --- a/lib/matplotlib/docstring.py +++ b/lib/matplotlib/docstring.py @@ -37,7 +37,7 @@ def __init__(self, *args, **kwargs): def __call__(self, func): if func.__doc__: - func.__doc__ %= self.params + func.__doc__ = inspect.cleandoc(func.__doc__) % self.params return func def update(self, *args, **kwargs): @@ -72,9 +72,4 @@ def do_copy(target): # Create a decorator that will house the various docstring snippets reused # throughout Matplotlib. interpd = Substitution() - - -def dedent_interpd(func): - """Dedent *func*'s docstring, then interpolate it with ``interpd``.""" - func.__doc__ = inspect.getdoc(func) - return interpd(func) +dedent_interpd = interpd