8000 Merge pull request #23574 from anntzer/cbd · matplotlib/matplotlib@a413677 · GitHub
[go: up one dir, main page]
Skip to content

Commit a413677

Browse files
timhoffmtimhoffm
authored
Merge pull request #23574 from anntzer/cbd
Move colorbar() doc to method itself.
2 parents 384a92e + 0015687 commit a413677

File tree

2 files changed

+79
-83
lines changed

2 files changed

+79
-83
lines changed

‎lib/matplotlib/colorbar.py

Lines changed: 11 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212
"""
1313

1414
import logging
15-
import textwrap
1615

1716
import numpy as np
1817

@@ -28,7 +27,8 @@
2827

2928
_log = logging.getLogger(__name__)
3029

31-
_make_axes_kw_doc = """
30+
_docstring.interpd.update(
31+
_make_axes_kw_doc="""
3232
location : None or {'left', 'right', 'top', 'bottom'}
3333
The location, relative to the parent axes, where the colorbar axes
3434
is created. It also determines the *orientation* of the colorbar
@@ -61,10 +61,8 @@
6161
panchor : (float, float), or *False*, optional
6262
The anchor point of the colorbar parent axes. If *False*, the parent
6363
axes' anchor will be unchanged.
64-
Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
65-
"""
66-
67-
_colormap_kw_doc = """
64+
Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.""",
65+
_colormap_kw_doc="""
6866
extend : {'neither', 'both', 'min', 'max'}
6967
Make pointed end(s) for out-of-range values (unless 'neither'). These are
7068
set for a given colormap using the colormap set_under and set_over methods.
@@ -114,76 +112,7 @@
114112
each region delimited by adjacent entries in *boundaries*, the color mapped
115113
to the corresponding value in values will be used.
116114
Normally only useful for indexed colors (i.e. ``norm=NoNorm()``) or other
117-
unusual circumstances.
118-
"""
119-
120-
_docstring.interpd.update(colorbar_doc="""
121-
Add a colorbar to a plot.
122-
123-
Parameters
124-
----------
125-
mappable
126-
The `matplotlib.cm.ScalarMappable` (i.e., `~matplotlib.image.AxesImage`,
127-
`~matplotlib.contour.ContourSet`, etc.) described by this colorbar.
128-
This argument is mandatory for the `.Figure.colorbar` method but optional
129-
for the `.pyplot.colorbar` function, which sets the default to the current
130-
image.
131-
132-
Note that one can create a `.ScalarMappable` "on-the-fly" to generate
133-
colorbars not attached to a previously drawn artist, e.g. ::
134-
135-
fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)
136-
137-
cax : `~matplotlib.axes.Axes`, optional
138-
Axes into which the colorbar will be drawn.
139-
140-
ax : `~matplotlib.axes.Axes`, list of Axes, optional
141-
One or more parent axes from which space for a new colorbar axes will be
142-
stolen, if *cax* is None. This has no effect if *cax* is set.
143-
144-
use_gridspec : bool, optional
145-
If *cax* is ``None``, a new *cax* is created as an instance of Axes. If
146-
*ax* is an instance of Subplot and *use_gridspec* is ``True``, *cax* is
147-
created as an instance of Subplot using the :mod:`.gridspec` module.
148-
149-
Returns
150-
-------
151-
colorbar : `~matplotlib.colorbar.Colorbar`
152-
153-
Notes
154-
-----
155-
Additional keyword arguments are of two kinds:
156-
157-
axes properties:
158-
%s
159-
colorbar properties:
160-
%s
161-
162-
If *mappable* is a `~.contour.ContourSet`, its *extend* kwarg is included
163-
automatically.
164-
165-
The *shrink* kwarg provides a simple way to scale the colorbar with respect
166-
to the axes. Note that if *cax* is specified, it determines the size of the
167-
colorbar and *shrink* and *aspect* kwargs are ignored.
168-
169-
For more precise control, you can manually specify the positions of
170-
the axes objects in which the mappable and the colorbar are drawn. In
171-
this case, do not use any of the axes properties kwargs.
172-
173-
It is known that some vector graphics viewers (svg and pdf) renders white gaps
174-
between segments of the colorbar. This is due to bugs in the viewers, not
175-
Matplotlib. As a workaround, the colorbar can be rendered with overlapping
176-
segments::
177-
178-
cbar = colorbar()
179-
cbar.solids.set_edgecolor("face")
180-
draw()
181-
182-
However this has negative consequences in other circumstances, e.g. with
183-
semi-transparent images (alpha < 1) and colorbar extensions; therefore, this
184-
workaround is not used by default (see issue #1188).
185-
""" % (textwrap.indent(_make_axes_kw_doc, " "),
186-
textwrap.indent(_colormap_kw_doc, " ")))
115+
unusual circumstances.""")
187116

188117

189118
def _set_ticks_on_axis_warn(*args, **kwargs):
@@ -267,7 +196,7 @@ def get_subplotspec(self):
267196
return ss()
268197

269198

270-
@_docstring.Substitution(_colormap_kw_doc)
199+
@_docstring.interpd
271200
class Colorbar:
272201
r"""
273202
Draw a colorbar in an existing axes.
@@ -327,7 +256,7 @@ class Colorbar:
327256
drawedges : bool
328257
329258
filled : bool
330-
%s
259+
%(_colormap_kw_doc)s
331260
"""
332261

333262
n_rasterize = 50 # rasterize solids if number of colors >= n_rasterize
@@ -1425,7 +1354,7 @@ def _normalize_location_orientation(location, orientation):
14251354
return loc_settings
14261355

14271356

1428-
@_docstring.Substitution(_make_axes_kw_doc)
1357+
@_docstring.interpd
14291358
def make_axes(parents, location=None, orientation=None, fraction=0.15,
14301359
shrink=1.0, aspect=20, **kwargs):
14311360
"""
@@ -1438,7 +1367,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
14381367
----------
14391368
parents : `~.axes.Axes` or list of `~.axes.Axes`
14401369
The Axes to use as parents for placing the colorbar.
1441-
%s
1370+
%(_make_axes_kw_doc)s
14421371
14431372
Returns
14441373
-------
@@ -1527,7 +1456,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
15271456
return cax, kwargs
15281457

15291458

1530-
@_docstring.Substitution(_make_axes_kw_doc)
1459+
@_docstring.interpd
15311460
def make_axes_gridspec(parent, *, location=None, orientation=None,
15321461
fraction=0.15, shrink=1.0, aspect=20, **kwargs):
15331462
"""
@@ -1553,7 +1482,7 @@ def make_axes_gridspec(parent, *, location=None, orientation=None,
15531482
----------
15541483
parent : `~.axes.Axes`
15551484
The Axes to use as parent for placing the colorbar.
1556-
%s
1485+
%(_make_axes_kw_doc)s
15571486
15581487
Returns
15591488
-------

‎lib/matplotlib/figure.py

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1178,7 +1178,74 @@ def text(self, x, y, s, fontdict=None, **kwargs):
11781178
@_docstring.dedent_interpd
11791179
def colorbar(
11801180
self, mappable, cax=None, ax=None, use_gridspec=True, **kwargs):
1181-
"""%(colorbar_doc)s"""
1181+
"""
1182+
Add a colorbar to a plot.
1183+
1184+
Parameters
1185+
----------
1186+
mappable
1187+
The `matplotlib.cm.ScalarMappable` (i.e., `.AxesImage`,
1188+
`.ContourSet`, etc.) described by this colorbar. This argument is
1189+
mandatory for the `.Figure.colorbar` method but optional for the
1190+
`.pyplot.colorbar` function, which sets the default to the current
1191+
image.
1192+
1193+
Note that one can create a `.ScalarMappable` "on-the-fly" to
1194+
generate colorbars not attached to a previously drawn artist, e.g.
1195+
::
1196+
1197+
fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)
1198+
1199+
cax : `~matplotlib.axes.Axes`, optional
1200+
Axes into which the colorbar will be drawn.
1201+
1202+
ax : `~matplotlib.axes.Axes`, list of Axes, optional
1203+
One or more parent axes from which space for a new colorbar axes
1204+
will be stolen, if *cax* is None. This has no effect if *cax* is
1205+
set.
1206+
1207+
use_gridspec : bool, optional
1208+
If *cax* is ``None``, a new *cax* is created as an instance of
1209+
Axes. If *ax* is an instance of Subplot and *use_gridspec* is
1210+
``True``, *cax* is created as an instance of Subplot using the
1211+
:mod:`.gridspec` module.
1212+
1213+
Returns
1214+
-------
1215+
colorbar : `~matplotlib.colorbar.Colorbar`
1216+
1217+
Other Parameters
1218+
----------------
1219+
%(_make_axes_kw_doc)s
1220+
%(_colormap_kw_doc)s
1221+
1222+
Notes
1223+
-----
1224+
If *mappable* is a `~.contour.ContourSet`, its *extend* kwarg is
1225+
included automatically.
1226+
1227+
The *shrink* kwarg provides a simple way to scale the colorbar with
1228+
respect to the axes. Note that if *cax* is specified, it determines the
1229+
size of the colorbar and *shrink* and *aspect* kwargs are ignored.
1230+
1231+
For more precise control, you can manually specify the positions of the
1232+
axes objects in which the mappable and the colorbar are drawn. In this
1233+
case, do not use any of the axes properties kwargs.
1234+
1235+
It is known that some vector graphics viewers (svg and pdf) renders
1236+
white gaps between segments of the colorbar. This is due to bugs in
1237+
the viewers, not Matplotlib. As a workaround, the colorbar can be
1238+
rendered with overlapping segments::
1239+
1240+
cbar = colorbar()
1241+
cbar.solids.set_edgecolor("face")
1242+
draw()
1243+
1244+
However this has negative consequences in other circumstances, e.g.
1245+
with semi-transparent images (alpha < 1) and colorbar extensions;
1246+
therefore, this workaround is not used by default (see issue #1188).
1247+
"""
1248+
11821249
if ax is None:
11831250
ax = getattr(mappable, "axes", self.gca())
11841251

0 commit comments

Comments
 (0)
0