8000 Update docstrings in figure.py. · matplotlib/matplotlib@5e5127b · GitHub
[go: up one dir, main page]
Skip to content

Commit 5e5127b

Browse files
anntzeranntzer
committed
Update docstrings in figure.py.
1 parent 76c764c commit 5e5127b

File tree

1 file changed

+33
-41
lines changed

1 file changed

+33
-41
lines changed

‎lib/matplotlib/figure.py

Lines changed: 33 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
"""
2-
The figure module provides the top-level
3-
:class:`~matplotlib.artist.Artist`, the :class:`Figure`, which
4-
contains all the plot elements. The following classes are defined
2+
`matplotlib.figure` implements the following classes:
53
6-
:class:`SubplotParams`
7-
control the default spacing of the subplots
4+
`Figure`
5+
Top level `~matplotlib.artist.Artist`, which holds all plot elements.
86
9-
:class:`Figure`
10-
Top level container for all plot elements.
7+
`SubplotParams`
8+
Control the default spacing between subplots.
119
"""
1210

1311
import logging
@@ -47,20 +45,18 @@ def _stale_figure_callback(self, val):
4745

4846
class _AxesStack(cbook.Stack):
4947
"""
50-
Specialization of the `.Stack` to handle all tracking of
51-
`~matplotlib.axes.Axes` in a `.Figure`.
52-
This stack stores ``key, (ind, axes)`` pairs, where:
48+
Specialization of `.Stack`, to handle all tracking of `~.axes.Axes` in a
49+
`.Figure`.
5350
54-
* **key** should be a hash of the args and kwargs
55-
used in generating the Axes.
56-
* **ind** is a serial number for tracking the order
57-
in which axes were added.
51+
This stack stores ``key, (ind, axes)`` pairs, where:
5852
59-
The AxesStack is a callable, where ``ax_stack()`` returns
60-
the current axes. Alternatively the :meth:`current_key_axes` will
61-
return the current key and associated axes.
53+
* **key** is a hash of the args and kwargs used in generating the Axes.
54+
* **ind** is a serial index tracking the order in which axes were added.
6255
56+
AxesStack is a callable; calling it returns the current axes.
57+
The `current_key_axes` method returns the current key and associated axes.
6358
"""
59+
6460
def __init__(self):
6561
super().__init__()
6662
self._ind = 0
@@ -284,7 +280,7 @@ def __init__(self,
284280
frameon : bool, default: :rc:`figure.frameon`
285281
If ``False``, suppress drawing the figure background patch.
286282
287-
subplotpars : :class:`SubplotParams`
283+
subplotpars : `SubplotParams`
288284
Subplot parameters. If not given, the default subplot
289285
parameters :rc:`figure.subplot.*` are used.
290286
@@ -384,10 +380,9 @@ def show(self, warn=True):
384380
"""
385381
If using a GUI backend with pyplot, display the figure window.
386382
387-
If the figure was not created using
388-
:func:`~matplotlib.pyplot.figure`, it will lack a
389-
:class:`~matplotlib.backend_bases.FigureManagerBase`, and
390-
will raise an AttributeError.
383+
If the figure was not created using `~.pyplot.figure`, it will lack
384+
a `~.backend_bases.FigureManagerBase`, and this method will raise an
385+
AttributeError.
391386
392387
.. warning::
393388
This does not manage an GUI event loop. Consequently, the figure
@@ -403,7 +398,7 @@ def show(self, warn=True):
403398
404399
Parameters
405400
----------
406-
warn : bool
401+
warn : bool, default: True
407402
If ``True`` and we are not running headless (i.e. on Linux with an
408403
unset DISPLAY), issue warning when called on a non-GUI backend.
409404
"""
@@ -699,7 +694,7 @@ def suptitle(self, t, **kwargs):
699694
:rc:`figure.titleweight` are ignored in this case.
700695
701696
**kwargs
702-
Additional kwargs are :class:`matplotlib.text.Text` properties.
697+
Additional kwargs are `matplotlib.text.Text` properties.
703698
704699
Examples
705700
--------
@@ -782,7 +777,7 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
782777
The alpha blending value.
783778
784779
norm : `matplotlib.colors.Normalize`
785-
A :class:`.Normalize` instance to map the luminance to the
780+
A `.Normalize` instance to map the luminance to the
786781
interval [0, 1].
787782
788783
cmap : str or `matplotlib.colors.Colormap`, default: :rc:`image.cmap`
@@ -801,7 +796,7 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
801796
802797
Returns
803798
-------
804-
:class:`matplotlib.image.FigureImage`
799+
`matplotlib.image.FigureImage`
805800
806801
Other Parameters
807802
----------------
@@ -1019,11 +1014,11 @@ def set_frameon(self, b):
10191014

10201015
def add_artist(self, artist, clip=False):
10211016
"""
1022-
Add any :class:`~matplotlib.artist.Artist` to the figure.
1017+
Add an `.Artist` to the figure.
10231018
1024-
Usually artists are added to axes objects using
1025-
:meth:`matplotlib.axes.Axes.add_artist`, but use this method in the
1026-
rare cases that adding directly to the figure is necessary.
1019+
Usually artists are added to axes objects using `.Axes.add_artist`;
1020+
this method can be used in the rare cases where one needs to add
1021+
artists directly to the figure instead.
10271022
10281023
Parameters
10291024
----------
@@ -1451,9 +1446,8 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
14511446
up being 1x1.
14521447
14531448
subplot_kw : dict, optional
1454-
Dict with keywords passed to the
1455-
:meth:`~matplotlib.figure.Figure.add_subplot` call used to create
1456-
each subplot.
1449+
Dict with keywords passed to the `.Figure.add_subplot` call used to
1450+
create each subplot.
14571451
14581452
gridspec_kw : dict, optional
14591453
Dict with keywords passed to the
@@ -1667,9 +1661,7 @@ def clf(self, keep_observers=False):
16671661
self.stale = True
16681662

16691663
def clear(self, keep_observers=False):
1670-
"""
1671-
Clear the figure -- synonym for :meth:`clf`.
1672-
"""
1664+
"""Clear the figure -- synonym for `clf`."""
16731665
self.clf(keep_observers=keep_observers)
16741666

16751667
@allow_rasterization
@@ -1727,8 +1719,9 @@ def draw(self, renderer):
17271719

17281720
def draw_artist(self, a):
17291721
"""
1730-
Draw :class:`matplotlib.artist.Artist` instance *a* only.
1731-
This is available only after the figure is drawn.
1722+
Draw `.Artist` instance *a* only.
1723+
1724+
This can only be called after the figure has been drawn.
17321725
"""
17331726
if self._cachedRenderer is None:
17341727
raise AttributeError("draw_artist can only be used after an "
@@ -2206,9 +2199,8 @@ def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw):
22062199
def subplots_adjust(self, left=None, bottom=None, right=None, top=None,
22072200
wspace=None, hspace=None):
22082201
"""
2209-
Update the :class:`SubplotParams` with *kwargs* (defaulting to rc when
2210-
*None*) and update the subplot locations.
2211-
2202+
Update the `SubplotParams` with *kwargs* (defaulting to rc when
2203+
*None*), and update the subplot locations.
22122204
"""
22132205
if self.get_constrained_layout():
22142206
self.set_constrained_layout(False)

0 commit comments

Comments
 (0)
0