Improve properties formatting in interpolated docstrings.

anntzer · anntzer · commit 77a963395929 · 2019-05-26T08:49:22.000+02:00
This makes docstring interpolation a bit less sensitive to the indent
where the inserted string goes.  For example, the docstring of
`add_subplot` goes from

```
    **kwargs
        This method also takes the keyword arguments for
        the returned axes base class. The keyword arguments for the
        rectilinear base class `~.axes.Axes` can be found in
        the following table but there might also be other keyword
        arguments if another projection is used.
          adjustable: {'box', 'datalim'}
      agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
      alpha: float or None
      ...
```
to
```
    **kwargs
        This method also takes the keyword arguments for
        the returned axes base class. The keyword arguments for the
        rectilinear base class `~.axes.Axes` can be found in
        the following table but there might also be other keyword
        arguments if another projection is used.

        Properties:
        adjustable: {'box', 'datalim'}
        agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
        alpha: float or None
```
Note that this does not affect sphinx rendering as that uses
pprint_setters_rest.

Note that whether the properties list is indented relative to the
"Properties" header depends on the indent where the inserted string goes
(lines starting from the second one are *always* indented by 4
characters (8 looks like too much), but I think it's still an
(incremental) improvement.

Also make sure that the property list is preceded by a newline.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1575,12 +1575,10 @@ def kwdoc(artist):
         :rc:`docstring.hardcopy` is False and as a rst table (intended for
         use in Sphinx) if it is True.
     """
-    hardcopy = matplotlib.rcParams['docstring.hardcopy']
-    if hardcopy:
-        return '\n'.join(ArtistInspector(artist).pprint_setters_rest(
-                         leadingspace=4))
-    else:
-        return '\n'.join(ArtistInspector(artist).pprint_setters(
-                         leadingspace=2))
+    ai = ArtistInspector(artist)
+    return ('\n'.join(ai.pprint_setters_rest(leadingspace=4))
+            if matplotlib.rcParams['docstring.hardcopy'] else
+            'Properties:\n' + '\n'.join(ai.pprint_setters(leadingspace=4)))
+
 
 docstring.interpd.update(Artist=kwdoc(Artist))
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -393,7 +393,6 @@ def legend(self, *args, **kwargs):
         --------
 
         .. plot:: gallery/text_labels_and_annotations/legend.py
-
         """
         handles, labels, extra_args, kwargs = mlegend._parse_legend_args(
                 [self],
@@ -645,15 +644,12 @@ def secondary_xaxis(self, location, *, functions=None, **kwargs):
             ax.loglog(range(1, 360, 5), range(1, 360, 5))
             ax.set_xlabel('frequency [Hz]')
 
-
             def invert(x):
                 return 1 / x
 
             secax = ax.secondary_xaxis('top', functions=(invert, invert))
             secax.set_xlabel('Period [s]')
             plt.show()
-
-
         """
         if (location in ['top', 'bottom'] or isinstance(location, Number)):
             secondary_ax = SecondaryAxis(self, 'x', location, functions,
@@ -686,7 +682,6 @@ def secondary_yaxis(self, location, *, functions=None, **kwargs):
             secax = ax.secondary_yaxis('right', functions=(np.deg2rad,
                                                            np.rad2deg))
             secax.set_ylabel('radians')
-
         """
         if location in ['left', 'right'] or isinstance(location, Number):
             secondary_ax = SecondaryAxis(self, 'y', location,
@@ -845,7 +840,6 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs):
           the xrange::
 
             >>> axhline(y=.5, xmin=0.25, xmax=0.75)
-
         """
         if "transform" in kwargs:
             raise ValueError(
@@ -1714,15 +1708,13 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
 
         %(_Line2D_docstr)s
 
-
         See Also
         --------
         matplotlib.dates : Helper functions on dates.
         matplotlib.dates.date2num : Convert dates to num.
         matplotlib.dates.num2date : Convert num to dates.
         matplotlib.dates.drange : Create an equally spaced sequence of dates.
 
-
         Notes
         -----
         If you are using custom date tickers and formatters, it may be
@@ -2294,7 +2286,6 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
         Other optional kwargs:
 
         %(Rectangle)s
-
         """
         kwargs = cbook.normalize_kwargs(kwargs, mpatches.Patch)
         color = kwargs.pop('color', None)
@@ -2588,7 +2579,6 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
         Other optional kwargs:
 
         %(Rectangle)s
-
         """
         kwargs.setdefault('orientation', 'horizontal')
         patches = self.bar(x=left, height=height, width=width, bottom=y,
@@ -3203,7 +3193,6 @@ def errorbar(self, x, y, yerr=None, xerr=None,
             Valid kwargs for the marker properties are `.Lines2D` properties:
 
         %(_Line2D_docstr)s
-
         """
         kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
         # anything that comes in as 'None', drop so the default thing
@@ -4642,7 +4631,6 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
         :class:`~matplotlib.collections.Collection` parameters:
 
             %(Collection)s
-
         """
         self._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)
 
@@ -6059,7 +6047,6 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         %(QuadMesh)s
 
-
         See Also
         --------
         pcolor : An alternative implementation with slightly different
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -440,6 +440,7 @@ def __init__(self, fig, rect,
 
         **kwargs
             Other optional keyword arguments:
+
             %(Axes)s
 
         Returns
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1172,6 +1172,7 @@ def add_axes(self, *args, **kwargs):
             the following table but there might also be other keyword
             arguments if another projection is used, see the actual axes
             class.
+
             %(Axes)s
 
         Returns
@@ -1315,6 +1316,7 @@ def add_subplot(self, *args, **kwargs):
             rectilinear base class `~.axes.Axes` can be found in
             the following table but there might also be other keyword
             arguments if another projection is used.
+
             %(Axes)s
 
         Returns
@@ -1859,6 +1861,7 @@ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         ----------------
         **kwargs : `~matplotlib.text.Text` properties
             Other miscellaneous text parameters.
+
             %(Text)s
 
         Returns
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -605,6 +605,7 @@ def __init__(self, patch, ox, oy, props=None, **kwargs):
         but darkened.
 
         kwargs are
+
         %(Patch)s
         """
         Patch.__init__(self)
@@ -686,6 +687,7 @@ def __init__(self, xy, width, height, angle=0.0, **kwargs):
         Notes
         -----
         Valid kwargs are:
+
         %(Patch)s
         """
 
@@ -853,6 +855,7 @@ def __init__(self, xy, numVertices, radius=5, orientation=0,
           rotates the polygon (in radians).
 
         Valid kwargs are:
+
         %(Patch)s
         """
         self._xy = xy
@@ -930,6 +933,7 @@ def __init__(self, path, **kwargs):
         *path* is a :class:`matplotlib.path.Path` object.
 
         Valid kwargs are:
+
         %(Patch)s
         """
         Patch.__init__(self, **kwargs)
@@ -956,6 +960,7 @@ def __init__(self, xy, closed=True, **kwargs):
         starting and ending points are the same.
 
         Valid kwargs are:
+
         %(Patch)s
         """
         Patch.__init__(self, **kwargs)
@@ -1232,8 +1237,8 @@ def __init__(self, x, y, dx, dy, width=0.001, length_includes_head=False,
             instead of ending at coordinate 0.
 
         Other valid kwargs (inherited from :class:`Patch`) are:
-        %(Patch)s
 
+        %(Patch)s
         """
         if head_width is None:
             head_width = 3 * width
@@ -1313,8 +1318,8 @@ def __init__(self, xy, radius=5,
         see :class:`~matplotlib.patches.Circle`.
 
         Valid kwargs are:
-        %(Patch)s
 
+        %(Patch)s
         """
         RegularPolygon.__init__(self, xy,
                                 resolution,
@@ -1350,6 +1355,7 @@ def __init__(self, xy, width, height, angle=0, **kwargs):
         Notes
         -----
         Valid keyword arguments are
+
         %(Patch)s
         """
         Patch.__init__(self, **kwargs)
@@ -1424,8 +1430,8 @@ def __init__(self, xy, radius=5, **kwargs):
         and is much closer to a scale-free circle.
 
         Valid kwargs are:
-        %(Patch)s
 
+        %(Patch)s
         """
         Ellipse.__init__(self, xy, radius * 2, radius * 2, **kwargs)
         self.radius = radius
@@ -1505,7 +1511,6 @@ def __init__(self, xy, width, height, angle=0.0,
             not supported.
 
         %(Patch)s
-
         """
         fill = kwargs.setdefault('fill', False)
         if fill:
@@ -2606,7 +2611,6 @@ class ConnectionStyle(_Style):
 
     %(AvailableConnectorstyles)s
 
-
     An instance of any connection style class is an callable object,
     whose call signature is::
 
@@ -3051,7 +3055,6 @@ class ArrowStyle(_Style):
 
     %(AvailableArrowstyles)s
 
-
     An instance of any arrow style class is a callable object,
     whose call signature is::
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -783,6 +783,7 @@ def axes(arg=None, **kwargs):
         the following table but there might also be other keyword
         arguments if another projection is used, see the actual axes
         class.
+
         %(Axes)s
 
     Returns
@@ -933,6 +934,7 @@ def subplot(*args, **kwargs):
         rectilinear base class `~.axes.Axes` can be found in
         the following table but there might also be other keyword
         arguments if another projection is used.
+
         %(Axes)s
 
     Returns
diff --git a/lib/matplotlib/spines.py b/lib/matplotlib/spines.py
@@ -39,6 +39,7 @@ def __init__(self, axes, spine_type, path, **kwargs):
         - *path* : the path instance used to draw the spine
 
         Valid kwargs are:
+
         %(Patch)s
         """
         super().__init__(**kwargs)
diff --git a/lib/matplotlib/table.py b/lib/matplotlib/table.py
@@ -172,6 +172,7 @@ def set_text_props(self, **kwargs):
         Update the text properties.
 
         Valid kwargs are
+
         %(Text)s
         """
         self._text.update(kwargs)
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -136,9 +136,9 @@ def __init__(self,
         Create a `.Text` instance at *x*, *y* with string *text*.
 
         Valid kwargs are
+
         %(Text)s
         """
-
         Artist.__init__(self)
         self._x, self._y = x, y
 
diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -151,6 +151,7 @@ def __init__(self, bbox, **kwargs):
 
         **kwargs
             Patch properties. Valid arguments include:
+
             %(Patch)s
         """
         if "transform" in kwargs:
@@ -294,6 +295,7 @@ def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs):
 
         **kwargs
             Patch properties for the line drawn. Valid arguments include:
+
             %(Patch)s
         """
         if "transform" in kwargs:
@@ -352,6 +354,7 @@ def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs):
 
         **kwargs
             Patch properties for the line drawn:
+
             %(Patch)s
         """
         if "transform" in kwargs:
@@ -471,6 +474,7 @@ def inset_axes(parent_axes, width, height, loc='upper right',
     axes_kwargs : dict, optional
         Keyworded arguments to pass to the constructor of the inset axes.
         Valid arguments include:
+
         %(Axes)s
 
     borderpad : float, optional
@@ -588,6 +592,7 @@ def zoomed_inset_axes(parent_axes, zoom, loc='upper right',
     axes_kwargs : dict, optional
         Keyworded arguments to pass to the constructor of the inset axes.
         Valid arguments include:
+
         %(Axes)s
 
     borderpad : float, optional
@@ -644,6 +649,7 @@ def mark_inset(parent_axes, inset_axes, loc1, loc2, **kwargs):
 
     **kwargs
         Patch properties for the lines and box drawn:
+
         %(Patch)s
 
     Returns
