From be76dcd86b688b4be1f6acdca516b9f1160b7270 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sat, 7 Dec 2019 02:21:38 +0100 Subject: [PATCH] Docstrings cleanup in matplotlib.axes. Mostly removals of unnecessary :func:/:class:. --- lib/matplotlib/axes/_axes.py | 162 +++++++++++++++-------------------- lib/matplotlib/axes/_base.py | 5 +- 2 files changed, 68 insertions(+), 99 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 152d00b0e4a3..9f01e056c529 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -155,15 +155,14 @@ def set_title(self, label, fontdict=None, loc=None, pad=None, Returns ------- - text : :class:`~matplotlib.text.Text` + text : `.Text` The matplotlib text instance representing the title Other Parameters ---------------- - **kwargs : `~matplotlib.text.Text` properties - Other keyword arguments are text properties, see - :class:`~matplotlib.text.Text` for a list of valid text - properties. + **kwargs : `.Text` properties + Other keyword arguments are text properties, see `.Text` for a list + of valid text properties. """ if loc is None: loc = rcParams['axes.titlelocation'] @@ -912,13 +911,13 @@ def axline(self, xy1, xy2, **kwargs): Returns ------- - :class:`~matplotlib.lines.Line2D` + `.Line2D` Other Parameters ---------------- **kwargs - Valid kwargs are :class:`~matplotlib.lines.Line2D` properties, - with the exception of 'transform': + Valid kwargs are `.Line2D` properties, with the exception of + 'transform': %(_Line2D_docstr)s @@ -1285,14 +1284,12 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1, **kwargs : optional Other keyword arguments are line collection properties. See - :class:`~matplotlib.collections.LineCollection` for a list of - the valid properties. + `.LineCollection` for a list of the valid properties. Returns ------- - list : A list of :class:`~.collections.EventCollection` objects. - Contains the :class:`~.collections.EventCollection` that - were added. + list : list of `.EventCollection` + The `.EventCollection` that were added. Notes ----- @@ -1961,7 +1958,7 @@ def acorr(self, x, **kwargs): Notes ----- - The cross correlation is performed with :func:`numpy.correlate` with + The cross correlation is performed with `numpy.correlate` with ``mode = "full"``. """ return self.xcorr(x, x, **kwargs) @@ -2031,7 +2028,7 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none, Notes ----- - The cross correlation is performed with :func:`numpy.correlate` with + The cross correlation is performed with `numpy.correlate` with ``mode = "full"``. """ Nx = len(x) @@ -2597,7 +2594,7 @@ def broken_barh(self, xranges, yrange, **kwargs): Other Parameters ---------------- - **kwargs : :class:`.BrokenBarHCollection` properties + **kwargs : `.BrokenBarHCollection` properties Each *kwarg* can be either a single argument applying to all rectangles, e.g.:: @@ -2616,7 +2613,7 @@ def broken_barh(self, xranges, yrange, **kwargs): Returns ------- - collection : A :class:`~.collections.BrokenBarHCollection` + collection : `~.collections.BrokenBarHCollection` """ # process the unit information if len(xranges): @@ -2716,7 +2713,7 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0, Returns ------- - container : :class:`~matplotlib.container.StemContainer` + container : `.StemContainer` The container may be treated like a tuple (*markerline*, *stemlines*, *baseline*) @@ -2908,15 +2905,14 @@ def pie(self, x, explode=None, labels=None, colors=None, Returns ------- patches : list - A sequence of :class:`matplotlib.patches.Wedge` instances + A sequence of `matplotlib.patches.Wedge` instances texts : list - A list of the label :class:`matplotlib.text.Text` instances. + A list of the label `.Text` instances. autotexts : list - A list of :class:`~matplotlib.text.Text` instances for the numeric - labels. This will only be returned if the parameter *autopct* is - not *None*. + A list of `.Text` instances for the numeric labels. This will only + be returned if the parameter *autopct* is not *None*. Notes ----- @@ -3141,14 +3137,13 @@ def errorbar(self, x, y, yerr=None, xerr=None, Returns ------- - container : :class:`~.container.ErrorbarContainer` + container : `.ErrorbarContainer` The container contains: - plotline: `.Line2D` instance of x, y plot markers and/or line. - caplines: A tuple of `.Line2D` instances of the error bar caps. - - barlinecols: A tuple of - :class:`~matplotlib.collections.LineCollection` with the - horizontal and vertical error ranges. + - barlinecols: A tuple of `.LineCollection` with the horizontal and + vertical error ranges. Other Parameters ---------------- @@ -5035,11 +5030,11 @@ def fill(self, *args, data=None, **kwargs): Returns ------- - a list of :class:`~matplotlib.patches.Polygon` + list of `~matplotlib.patches.Polygon` Other Parameters ---------------- - **kwargs : :class:`~matplotlib.patches.Polygon` properties + **kwargs : `~matplotlib.patches.Polygon` properties Notes ----- @@ -7015,16 +7010,14 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None, See Also -------- - :func:`specgram` - :func:`specgram` differs in the default overlap; in not returning - the mean of the segment periodograms; in returning the times of the - segments; and in plotting a colormap instead of a line. - - :func:`magnitude_spectrum` - :func:`magnitude_spectrum` plots the magnitude spectrum. - - :func:`csd` - :func:`csd` plots the spectral density between two signals. + specgram + Differs in the default overlap; in not returning the mean of the + segment periodograms; in returning the times of the segments; and + in plotting a colormap instead of a line. + magnitude_spectrum + Plots the magnitude spectrum. + csd + Plots the spectral density between two signals. Notes ----- @@ -7132,8 +7125,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None, See Also -------- - :func:`psd` - :func:`psd` is the equivalent to setting y=x. + psd : is equivalent to setting ``y = x``. Notes ----- @@ -7224,21 +7216,15 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None, See Also -------- - :func:`psd` - :func:`psd` plots the power spectral density.`. - - :func:`angle_spectrum` - :func:`angle_spectrum` plots the angles of the corresponding - frequencies. - - :func:`phase_spectrum` - :func:`phase_spectrum` plots the phase (unwrapped angle) of the - corresponding frequencies. - - :func:`specgram` - :func:`specgram` can plot the magnitude spectrum of segments within - the signal in a colormap. - + psd + Plots the power spectral density. + angle_spectrum + Plots the angles of the corresponding frequencies. + phase_spectrum + Plots the phase (unwrapped angle) of the corresponding frequencies. + specgram + Can plot the magnitude spectrum of segments within the signal in a + colormap. """ if Fc is None: Fc = 0 @@ -7308,18 +7294,13 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None, See Also -------- - :func:`magnitude_spectrum` - :func:`angle_spectrum` plots the magnitudes of the corresponding - frequencies. - - :func:`phase_spectrum` - :func:`phase_spectrum` plots the unwrapped version of this - function. - - :func:`specgram` - :func:`specgram` can plot the angle spectrum of segments within the - signal in a colormap. - + magnitude_spectrum + Plots the magnitudes of the corresponding frequencies. + phase_spectrum + Plots the unwrapped version of this function. + specgram + Can plot the angle spectrum of segments within the signal in a + colormap. """ if Fc is None: Fc = 0 @@ -7380,17 +7361,13 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None, See Also -------- - :func:`magnitude_spectrum` - :func:`magnitude_spectrum` plots the magnitudes of the - corresponding frequencies. - - :func:`angle_spectrum` - :func:`angle_spectrum` plots the wrapped version of this function. - - :func:`specgram` - :func:`specgram` can plot the phase spectrum of segments within the - signal in a colormap. - + magnitude_spectrum + Plots the magnitudes of the corresponding frequencies. + angle_spectrum + Plots the wrapped version of this function. + specgram + Can plot the phase spectrum of segments within the signal in a + colormap. """ if Fc is None: Fc = 0 @@ -7519,9 +7496,7 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None, when a signal is acquired and then filtered and downsampled to baseband. - cmap - A :class:`matplotlib.colors.Colormap` instance; if *None*, use - default determined by rc + cmap : `.Colormap`, default: :rc:`image.cmap` xextent : *None* or (xmin, xmax) The image extent along the x-axis. The default sets *xmin* to the @@ -7545,25 +7520,22 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None, The times corresponding to midpoints of segments (i.e., the columns in *spectrum*). - im : instance of class :class:`~matplotlib.image.AxesImage` - The image created by imshow containing the spectrogram + im : instance of class `.AxesImage` + The image created by imshow containing the spectrogram. See Also -------- - :func:`psd` - :func:`psd` differs in the default overlap; in returning the mean - of the segment periodograms; in not returning times; and in - generating a line plot instead of colormap. - - :func:`magnitude_spectrum` + psd + Differs in the default overlap; in returning the mean of the + segment periodograms; in not returning times; and in generating a + line plot instead of colormap. + magnitude_spectrum A single spectrum, similar to having a single segment when *mode* is 'magnitude'. Plots a line instead of a colormap. - - :func:`angle_spectrum` + angle_spectrum A single spectrum, similar to having a single segment when *mode* is 'angle'. Plots a line instead of a colormap. - - :func:`phase_spectrum` + phase_spectrum A single spectrum, similar to having a single segment when *mode* is 'phase'. Plots a line instead of a colormap. @@ -7655,7 +7627,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None, If *precision* is 0, any non-zero value will be plotted. Otherwise, values of :math:`|Z| > precision` will be plotted. - For :class:`scipy.sparse.spmatrix` instances, you can also + For `scipy.sparse.spmatrix` instances, you can also pass 'present'. In this case any value present in the array will be plotted, even if it is identically zero. diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index 7e4027c22f67..5decc3655af2 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -1812,10 +1812,7 @@ def _sci(self, im): self._current_image = im def _gci(self): - """ - Helper for :func:`~matplotlib.pyplot.gci`; - do not use elsewhere. - """ + """Helper for `~matplotlib.pyplot.gci`; do not use elsewhere.""" return self._current_image def has_data(self):