8000 List existing rcParams in rcParams docstring. · matplotlib/matplotlib@916f4ff · GitHub
[go: up one dir, main page]
Skip to content

Commit 916f4ff

Browse files
anntzeranntzer
committed
List existing rcParams in rcParams docstring.
This is useful for those who mostly live at the command line, letting one see the list of rcParams with `pydoc matplotlib.rcParams` (for example). Making `Substitution` always perform docstring dedenting simplifies the implementation here; I'm not sure you'd ever\* want to do an un-dedented interpolation anyways... (\*for certain values of "ever") Fix colorbar docstrings indentation accordingly.
1 parent d3eaffd commit 916f4ff

File tree

4 files changed

+40
-36
lines changed

4 files changed

+40
-36
lines changed

‎doc/api/next_api_changes/behavior/18440-AL.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
docstring.Substitution now always dedents docstrings before string interpolation
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎lib/matplotlib/__init__.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@
104104

105105
# cbook must import matplotlib only within function
106106
# definitions, so it is safe to import from it here.
107-
from . import cbook, rcsetup
107+
from . import cbook, docstring, rcsetup
108108
from matplotlib.cbook import MatplotlibDeprecationWarning, sanitize_sequence
109109
from matplotlib.cbook import mplDeprecation # deprecated
110110
from matplotlib.rcsetup import validate_backend, cycler
@@ -635,13 +635,18 @@ def gen_candidates():
635635
_all_deprecated = {*_deprecated_map, *_deprecated_ignore_map}
636636

637637

638+
@docstring.Substitution("\n".join(map("- {}".format, rcsetup._validators)))
638639
class RcParams(MutableMapping, dict):
639640
"""
640641
A dictionary object including validation.
641642
642643
Validating functions are defined and associated with rc parameters in
643644
:mod:`matplotlib.rcsetup`.
644645
646+
The list of rcParams is:
647+
648+
%s
649+
645650
See Also
646651
--------
647652
:ref:`customizing-with-matplotlibrc-files`

‎lib/matplotlib/colorbar.py

Lines changed: 30 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333

3434
import copy
3535
import logging
36+
import textwrap
3637

3738
import numpy as np
3839

@@ -53,35 +54,34 @@
5354
_log = logging.getLogger(__name__)
5455

5556
_make_axes_param_doc = """
56-
location : None or {'left', 'right', 'top', 'bottom'}
57-
The location, relative to the parent axes, where the colorbar axes
58-
is created. It also determines the *orientation* of the colorbar
59-
(colorbars on the left and right are vertical, colorbars at the top
60-
and bottom are horizontal). If None, the location will come from the
61-
*orientation* if it is set (vertical colorbars on the right, horizontal
62-
ones at the bottom), or default to 'right' if *orientation* is unset.
63-
orientation : None or {'vertical', 'horizontal'}
64-
The orientation of the colorbar. It is preferrable to set the
65-
*location* of the colorbar, as that also determines the *orientation*;
66-
passing incompatible values for *location* and *orientation* raises an
67-
exception.
68-
fraction : float, default: 0.15
69-
Fraction of original axes to use for colorbar.
70-
shrink : float, default: 1.0
71-
Fraction by which to multiply the size of the colorbar.
72-
aspect : float, default: 20
73-
Ratio of long to short dimensions.
57+
location : None or {'left', 'right', 'top', 'bottom'}
58+
The location, relative to the parent axes, where the colorbar axes
59+
is created. It also determines the *orientation* of the colorbar
60+
(colorbars on the left and right are vertical, colorbars at the top
61+
and bottom are horizontal). If None, the location will come from the
62+
*orientation* if it is set (vertical colorbars on the right, horizontal
63+
ones at the bottom), or default to 'right' if *orientation* is unset.
64+
orientation : None or {'vertical', 'horizontal'}
65+
The orientation of the colorbar. It is preferrable to set the *location*
66+
of the colorbar, as that also determines the *orientation*; passing
67+
incompatible values for *location* and *orientation* raises an exception.
68+
fraction : float, default: 0.15
69+
Fraction of original axes to use for colorbar.
70+
shrink : float, default: 1.0
71+
Fraction by which to multiply the size of the colorbar.
72+
aspect : float, default: 20
73+
Ratio of long to short dimensions.
7474
"""
7575
_make_axes_other_param_doc = """
76-
pad : float, default: 0.05 if vertical, 0.15 if horizontal
77-
Fraction of original axes between colorbar and new image axes.
78-
anchor : (float, float), optional
79-
The anchor point of the colorbar axes.
80-
Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.
81-
panchor : (float, float), or *False*, optional
82-
The anchor point of the colorbar parent axes. If *False*, the parent
83-
axes' anchor will be unchanged.
84-
Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
76+
pad : float, default: 0.05 if vertical, 0.15 if horizontal
77+
Fraction of original axes between colorbar and new image axes.
78+
anchor : (float, float), optional
79+
The anchor point of the colorbar axes.
80+
Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.
81+
panchor : (float, float), or *False*, optional
82+
The anchor point of the colorbar parent axes. If *False*, the parent
83+
axes' anchor will be unchanged.
84+
Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
8585
"""
8686

8787
_colormap_kw_doc = """
@@ -214,7 +214,9 @@
214214
However this has negative consequences in other circumstances, e.g. with
215215
semi-transparent images (alpha < 1) and colorbar extensions; therefore, this
216216
workaround is not used by default (see issue #1188).
217-
""" % (_make_axes_param_doc, _make_axes_other_param_doc, _colormap_kw_doc))
217+
""" % (textwrap.indent(_make_axes_param_doc, " "),
218+
textwrap.indent(_make_axes_other_param_doc, " "),
219+
_colormap_kw_doc))
218220

219221
# Deprecated since 3.4.
220222
colorbar_doc = docstring.interpd.params["colorbar_doc"]

‎lib/matplotlib/docstring.py

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ def __init__(self, *args, **kwargs):
3737

3838
def __call__(self, func):
3939
if func.__doc__:
40-
func.__doc__ %= self.params
40+
func.__doc__ = inspect.cleandoc(func.__doc__) % self.params
4141
return func
4242

4343
def update(self, *args, **kwargs):
@@ -72,9 +72,4 @@ def do_copy(target):
7272
# Create a decorator that will house the various docstring snippets reused
7373
# throughout Matplotlib.
7474
interpd = Substitution()
75-
76-
77-
def dedent_interpd(func):
78-
"""Dedent *func*'s docstring, then interpolate it with ``interpd``."""
79-
func.__doc__ = inspect.getdoc(func)
80-
return interpd(func)
75+
dedent_interpd = interpd

0 commit comments

Comments
 (0)
0