From 0c4714b51f52c6ca249644d535b4cce216554483 Mon Sep 17 00:00:00 2001 From: Bingyao Liu Date: Wed, 10 Jul 2019 22:03:13 +0800 Subject: [PATCH] Improve indentation and referring of Line2D properties in docstrings. --- lib/matplotlib/axes/_axes.py | 114 +++++++++++++++------------------- lib/matplotlib/axes/_base.py | 8 +-- lib/matplotlib/collections.py | 12 ++-- lib/matplotlib/lines.py | 15 +++-- lib/matplotlib/patches.py | 18 +++--- lib/matplotlib/table.py | 2 +- lib/matplotlib/text.py | 2 +- 7 files changed, 79 insertions(+), 92 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index ebb1002fdd7d..8434bd158f77 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -428,7 +428,7 @@ def inset_axes(self, bounds, *, transform=None, zorder=5, parent axes. **kwargs - Other *kwargs* are passed on to the `~.axes.Axes` child axes. + Other keyword arguments are passed on to the `.Axes` child axes. Returns ------- @@ -510,7 +510,7 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None, (just below the default level of inset axes). **kwargs - Other *kwargs* are passed on to the rectangle patch. + Other keyword arguments are passed on to the rectangle patch. Returns ------- @@ -596,7 +596,7 @@ def indicate_inset_zoom(self, inset_ax, **kwargs): chosen so as to not overlap with the indicator box. **kwargs - Other *kwargs* are passed on to `.Axes.indicate_inset` + Other keyword arguments are passed on to `.Axes.indicate_inset` Returns ------- @@ -802,15 +802,15 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs): Returns ------- - line : :class:`~matplotlib.lines.Line2D` + line : `~matplotlib.lines.Line2D` Other Parameters ---------------- **kwargs - Valid kwargs are :class:`~matplotlib.lines.Line2D` properties, - with the exception of 'transform': + Valid keyword arguments are `.Line2D` properties, with the + exception of 'transform': - %(_Line2D_docstr)s + %(_Line2D_docstr)s See also -------- @@ -870,15 +870,15 @@ def axvline(self, x=0, ymin=0, ymax=1, **kwargs): Returns ------- - line : :class:`~matplotlib.lines.Line2D` + line : `~matplotlib.lines.Line2D` Other Parameters ---------------- **kwargs - Valid kwargs are :class:`~matplotlib.lines.Line2D` properties, - with the exception of 'transform': + Valid keyword arguments are `.Line2D` properties, with the + exception of 'transform': - %(_Line2D_docstr)s + %(_Line2D_docstr)s Examples -------- @@ -1543,7 +1543,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs): Here is a list of available `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s Returns ------- @@ -1684,16 +1684,15 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False, Returns ------- lines - A list of `~.Line2D` objects representing the plotted data. + A list of `.Line2D` objects representing the plotted data. Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s See Also -------- @@ -1760,7 +1759,7 @@ def loglog(self, *args, **kwargs): Returns ------- lines - A list of `~.Line2D` objects representing the plotted data. + A list of `.Line2D` objects representing the plotted data. Other Parameters ---------------- @@ -1813,7 +1812,7 @@ def semilogx(self, *args, **kwargs): Returns ------- lines - A list of `~.Line2D` objects representing the plotted data. + A list of `.Line2D` objects representing the plotted data. Other Parameters ---------------- @@ -1862,7 +1861,7 @@ def semilogy(self, *args, **kwargs): Returns ------- lines - A list of `~.Line2D` objects representing the plotted data. + A list of `.Line2D` objects representing the plotted data. Other Parameters ---------------- @@ -3147,10 +3146,8 @@ def errorbar(self, x, y, yerr=None, xerr=None, container : :class:`~.container.ErrorbarContainer` The container contains: - - plotline: :class:`~matplotlib.lines.Line2D` instance of - x, y plot markers and/or line. - - caplines: A tuple of :class:`~matplotlib.lines.Line2D` instances - of the error bar caps. + - 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. @@ -3172,7 +3169,7 @@ def errorbar(self, x, y, yerr=None, xerr=None, Valid kwargs for the marker properties are `.Lines2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s """ kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D) # anything that comes in as 'None', drop so the default thing @@ -3620,9 +3617,8 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None, ------- result : dict A dictionary mapping each component of the boxplot to a list - of the :class:`matplotlib.lines.Line2D` instances - created. That dictionary has the following keys (assuming - vertical boxplots): + of the `.Line2D` instances created. That dictionary has the + following keys (assuming vertical boxplots): - ``boxes``: the main body of the boxplot showing the quartiles and the median's confidence intervals if @@ -3820,9 +3816,8 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True, makes horizontal boxes. patch_artist : bool, default = False - If `False` produces boxes with the - `~matplotlib.lines.Line2D` artist. If `True` produces boxes - with the `~matplotlib.patches.Patch` artist. + If `False` produces boxes with the `.Line2D` artist. + If `True` produces boxes with the `~matplotlib.patches.Patch` artist. shownotches : bool, default = False If `False` (default), produces a rectangular box plot. @@ -3875,9 +3870,8 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True, ------- result : dict A dictionary mapping each component of the boxplot to a list - of the :class:`matplotlib.lines.Line2D` instances - created. That dictionary has the following keys (assuming - vertical boxplots): + of the `.Line2D` instances created. That dictionary has the + following keys (assuming vertical boxplots): - ``boxes``: the main body of the boxplot showing the quartiles and the median's confidence intervals if @@ -7008,17 +7002,16 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None, freqs : 1-D array The frequencies corresponding to the elements in *Pxx*. - line : a :class:`~matplotlib.lines.Line2D` instance + line : `~matplotlib.lines.Line2D` The line created by this function. Only returned if *return_line* is True. Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s See Also -------- @@ -7127,17 +7120,16 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None, freqs : 1-D array The frequencies corresponding to the elements in *Pxy*. - line : a :class:`~matplotlib.lines.Line2D` instance + line : `~matplotlib.lines.Line2D` The line created by this function. Only returned if *return_line* is True. Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s See Also -------- @@ -7221,16 +7213,15 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None, freqs : 1-D array The frequencies corresponding to the elements in *spectrum*. - line : a :class:`~matplotlib.lines.Line2D` instance + line : `~matplotlib.lines.Line2D` The line created by this function. Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s See Also -------- @@ -7309,16 +7300,15 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None, freqs : 1-D array The frequencies corresponding to the elements in *spectrum*. - line : a :class:`~matplotlib.lines.Line2D` instance + line : `~matplotlib.lines.Line2D` The line created by this function. Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s See Also -------- @@ -7382,16 +7372,15 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None, freqs : 1-D array The frequencies corresponding to the elements in *spectrum*. - line : a :class:`~matplotlib.lines.Line2D` instance + line : `~matplotlib.lines.Line2D` The line created by this function. Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s See Also -------- @@ -7463,10 +7452,9 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, Other Parameters ---------------- **kwargs - Keyword arguments control the :class:`~matplotlib.lines.Line2D` - properties: + Keyword arguments control the `.Line2D` properties: - %(_Line2D_docstr)s + %(_Line2D_docstr)s References ---------- @@ -7546,8 +7534,8 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None, of the bins is smaller than those of the segments. **kwargs - Additional kwargs are passed on to imshow which makes the - specgram image. + Additional keyword arguments are passed on to imshow which makes + the specgram image. Returns ------- @@ -7653,14 +7641,14 @@ def spy(self, Z, precision=0, marker=None, markersize=None, **Image style** If *marker* and *markersize* are *None*, `~.Axes.imshow` is used. Any - extra remaining kwargs are passed to this method. + extra remaining keyword arguments are passed to this method. **Marker style** If *Z* is a `scipy.sparse.spmatrix` or *marker* or *markersize* are - *None*, a `~matplotlib.lines.Line2D` object will be returned with - the value of marker determining the marker type, and any - remaining kwargs passed to `~.Axes.plot`. + *None*, a `.Line2D` object will be returned with the value of marker + determining the marker type, and any remaining keyword arguments + passed to `~.Axes.plot`. Parameters ---------- @@ -7719,7 +7707,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None, For the marker style, you can pass any `.Line2D` property except for *linestyle*: - %(_Line2D_docstr)s + %(_Line2D_docstr)s """ if marker is None and markersize is None and hasattr(Z, 'tocoo'): marker = 's' diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index fb0000b9a909..408408d259c0 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -1840,7 +1840,7 @@ def _update_image_limits(self, image): def add_line(self, line): """ - Add a `~.Line2D` to the axes' lines; return the line. + Add a `.Line2D` to the axes' lines; return the line. """ self._set_artist_props(line) if line.get_clip_path() is None: @@ -2741,9 +2741,9 @@ def grid(self, b=None, which='major', axis='both', **kwargs): grid(color='r', linestyle='-', linewidth=2) - Valid *kwargs* are + Valid keyword arguments are: - %(_Line2D_docstr)s + %(_Line2D_docstr)s Notes ----- @@ -2921,7 +2921,7 @@ def tick_params(self, axis='both', **kwargs): grid_linewidth : float Width of gridlines in points. grid_linestyle : str - Any valid `~matplotlib.lines.Line2D` line style spec. + Any valid `.Line2D` line style spec. Examples -------- diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index f9fff1312e3a..3f9a6d5ece09 100644 --- a/lib/matplotlib/collections.py +++ b/lib/matplotlib/collections.py @@ -960,12 +960,12 @@ def legend_elements(self, prop="colors", num="auto", the legend labels have the correct values; e.g. *func = np.exp(x, 10)*. kwargs : further parameters - Allowed kwargs are *color* and *size*. E.g. it may be useful to - set the color of the markers if *prop="sizes"* is used; similarly - to set the size of the markers if *prop="colors"* is used. - Any further parameters are passed onto the `.Line2D` instance. - This may be useful to e.g. specify a different *markeredgecolor* or - *alpha* for the legend handles. + Allowed keyword arguments are *color* and *size*. E.g. it may be + useful to set the color of the markers if *prop="sizes"* is used; + similarly to set the size of the markers if *prop="colors"* is + used. Any further parameters are passed onto the `.Line2D` + instance. This may be useful to e.g. specify a different + *markeredgecolor* or *alpha* for the legend handles. Returns ------- diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py index 44c1ba1b5491..c67c6f35f8e1 100644 --- a/lib/matplotlib/lines.py +++ b/lib/matplotlib/lines.py @@ -288,10 +288,10 @@ def __init__(self, xdata, ydata, **kwargs ): """ - Create a :class:`~matplotlib.lines.Line2D` instance with *x* - and *y* data in sequences *xdata*, *ydata*. + Create a `.Line2D` instance with *x* and *y* data in sequences of + *xdata*, *ydata*. - The kwargs are :class:`~matplotlib.lines.Line2D` properties: + Additional keyword arguments are `.Line2D` properties: %(_Line2D_docstr)s @@ -1451,7 +1451,7 @@ def is_dashed(self): class VertexSelector: """ Manage the callbacks to maintain a list of selected vertices for - :class:`matplotlib.lines.Line2D`. Derived classes should override + `.Line2D`. Derived classes should override :meth:`~matplotlib.lines.VertexSelector.process_selected` to do something with the picks. @@ -1481,10 +1481,9 @@ def process_selected(self, ind, xs, ys): """ def __init__(self, line): """ - Initialize the class with a :class:`matplotlib.lines.Line2D` - instance. The line should already be added to some - :class:`matplotlib.axes.Axes` instance and should have the - picker property set. + Initialize the class with a `.Line2D` instance. The line should + already be added to some :class:`matplotlib.axes.Axes` instance and + should have the picker property set. """ if line.axes is None: raise RuntimeError('You must first add the line to the Axes') diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 261dd50a730e..995c9242fdf2 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -601,7 +601,7 @@ def __init__(self, patch, ox, oy, props=None, **kwargs): If *None*, the shadow will have have the same color as the face, but darkened. - kwargs are + Valid keyword arguments are: %(Patch)s """ @@ -683,7 +683,7 @@ def __init__(self, xy, width, height, angle=0.0, **kwargs): Notes ----- - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ @@ -854,7 +854,7 @@ def __init__(self, xy, numVertices, radius=5, orientation=0, *orientation* rotates the polygon (in radians). - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ @@ -932,7 +932,7 @@ def __init__(self, path, **kwargs): """ *path* is a :class:`matplotlib.path.Path` object. - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ @@ -962,7 +962,7 @@ def __init__(self, xy, closed=True, **kwargs): If *closed* is *True*, the polygon will be closed so the starting and ending points are the same. - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ @@ -1061,7 +1061,7 @@ def __init__(self, center, r, theta1, theta2, width=None, **kwargs): then a partial wedge is drawn from inner radius *r* - *width* to outer radius *r*. - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ @@ -1312,7 +1312,7 @@ def __init__(self, xy, radius=5, *resolution* sides. For a smoother circle drawn with splines, see :class:`~matplotlib.patches.Circle`. - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ @@ -1349,7 +1349,7 @@ def __init__(self, xy, width, height, angle=0, **kwargs): Notes ----- - Valid keyword arguments are + Valid keyword arguments are: %(Patch)s """ @@ -1427,7 +1427,7 @@ def __init__(self, xy, radius=5, **kwargs): which is a polygonal approximation, this uses Bezier splines and is much closer to a scale-free circle. - Valid kwargs are: + Valid keyword arguments are: %(Patch)s """ diff --git a/lib/matplotlib/table.py b/lib/matplotlib/table.py index 2c59e59e95c5..4f5dd02d0514 100644 --- a/lib/matplotlib/table.py +++ b/lib/matplotlib/table.py @@ -171,7 +171,7 @@ def set_text_props(self, **kwargs): """ Update the text properties. - Valid kwargs are + Valid keyword arguments are: %(Text)s """ diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py index aaa24d982a02..b4b1013e08e7 100644 --- a/lib/matplotlib/text.py +++ b/lib/matplotlib/text.py @@ -135,7 +135,7 @@ def __init__(self, """ Create a `.Text` instance at *x*, *y* with string *text*. - Valid kwargs are + Valid keyword arguments are: %(Text)s """