Merge pull request #17752 from QuLogic/doc-normalize

timhoffm · web-flow · commit 224e45186e92 · 2020-06-26T08:40:49.000+02:00
Numpydoc-ify various functions
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5329,7 +5329,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
                origin=None, extent=None, *, filternorm=True, filterrad=4.0,
                resample=None, url=None, **kwargs):
         """
-        Display data as an image; i.e. on a 2D regular raster.
+        Display data as an image, i.e., on a 2D regular raster.
 
         The input may either be actual RGB(A) data, or 2D scalar data, which
         will be rendered as a pseudocolor image. For displaying a grayscale
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -54,25 +54,26 @@
 
 _log = logging.getLogger(__name__)
 
-make_axes_kw_doc = """
-
-    ============= ====================================================
-    Property      Description
-    ============= ====================================================
-    *orientation* vertical or horizontal
-    *fraction*    0.15; fraction of original axes to use for colorbar
-    *pad*         0.05 if vertical, 0.15 if horizontal; fraction
-                  of original axes between colorbar and new image axes
-    *shrink*      1.0; fraction by which to multiply the size of the colorbar
-    *aspect*      20; ratio of long to short dimensions
-    *anchor*      (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal;
-                  the anchor point of the colorbar axes
-    *panchor*     (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal;
-                  the anchor point of the colorbar parent axes. If
-                  False, the parent axes' anchor will be unchanged
-    ============= ====================================================
-
+_make_axes_param_doc = """
+    fraction : float, default: 0.15
+        Fraction of original axes to use for colorbar.
+    shrink : float, default: 1.0
+        Fraction by which to multiply the size of the colorbar.
+    aspect : float, default: 20
+        Ratio of long to short dimensions.
+"""
+_make_axes_other_param_doc = """
+    pad : float, default: 0.05 if vertical, 0.15 if horizontal
+        Fraction of original axes between colorbar and new image axes.
+    anchor : (float, float), optional
+        The anchor point of the colorbar axes.
+        Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.
+    panchor : (float, float), or *False*, optional
+        The anchor point of the colorbar parent axes. If *False*, the parent
+        axes' anchor will be unchanged.
+        Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
 """
+make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc
 
 colormap_kw_doc = """
 
@@ -1362,7 +1363,7 @@ def remove(self):
             ax.set_subplotspec(subplotspec)
 
 
-@docstring.Substitution(make_axes_kw_doc)
+@docstring.Substitution(_make_axes_param_doc, _make_axes_other_param_doc)
 def make_axes(parents, location=None, orientation=None, fraction=0.15,
               shrink=1.0, aspect=20, **kw):
     """
@@ -1371,21 +1372,33 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
     The axes is placed in the figure of the *parents* axes, by resizing and
     repositioning *parents*.
 
-    Keyword arguments may include the following (with defaults):
+    Parameters
+    ----------
+    parents : `~.axes.Axes` or list of `~.axes.Axes`
+        The Axes to use as parents for placing the colorbar.
 
-        location : None or {'left', 'right', 'top', 'bottom'}
-            The position, relative to *parents*, where the colorbar axes
-            should be created. If None, the value will either come from the
-            given ``orientation``, else it will default to 'right'.
+    location : None or {'left', 'right', 'top', 'bottom'}
+        The position, relative to *parents*, where the colorbar axes
+        should be created. If None, the value will either come from the
+        given ``orientation``, else it will default to 'right'.
 
-        orientation : None or {'vertical', 'horizontal'}
-            The orientation of the colorbar. Typically, this keyword shouldn't
-            be used, as it can be derived from the ``location`` keyword.
+    orientation : None or {'vertical', 'horizontal'}
+        The orientation of the colorbar. Typically, this keyword shouldn't
+        be used, as it can be derived from the ``location`` keyword.
 
     %s
 
-    Returns (cax, kw), the child axes and the reduced kw dictionary to be
-    passed when creating the colorbar instance.
+    Returns
+    -------
+    cax : `~.axes.Axes`
+        The child axes.
+    kw : dict
+        The reduced keyword dictionary to be passed when creating the colorbar
+        instance.
+
+    Other Parameters
+    ----------------
+    %s
     """
     locations = ["left", "right", "top", "bottom"]
     if orientation is not None and location is not None:
@@ -1519,7 +1532,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
     return cax, kw
 
 
-@docstring.Substitution(make_axes_kw_doc)
+@docstring.Substitution(_make_axes_param_doc, _make_axes_other_param_doc)
 def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw):
     """
     Create a `~.SubplotBase` suitable for a colorbar.
@@ -1530,30 +1543,40 @@ def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw):
     This function is similar to `.make_axes`. Primary differences are
 
     - `.make_axes_gridspec` only handles the *orientation* keyword
-      and cannot handle the "location" keyword.
+      and cannot handle the *location* keyword.
 
     - `.make_axes_gridspec` should only be used with a `.SubplotBase` parent.
 
     - `.make_axes` creates an `~.axes.Axes`; `.make_axes_gridspec` creates a
       `.SubplotBase`.
 
     - `.make_axes` updates the position of the parent.  `.make_axes_gridspec`
-       replaces the ``grid_spec`` attribute of the parent with a new one.
+      replaces the ``grid_spec`` attribute of the parent with a new one.
 
     While this function is meant to be compatible with `.make_axes`,
     there could be some minor differences.
 
-    Keyword arguments may include the following (with defaults):
-
-        *orientation*
-            'vertical' or 'horizontal'
+    Parameters
+    ----------
+    parent : `~.axes.Axes`
+        The Axes to use as parent for placing the colorbar.
 
     %s
 
-    All but the first of these are stripped from the input kw set.
+    Returns
+    -------
+    cax : `~.axes.SubplotBase`
+        The child axes.
+    kw : dict
+        The reduced keyword dictionary to be passed when creating the colorbar
+        instance.
 
-    Returns (cax, kw), the child axes and the reduced kw dictionary to be
-    passed when creating the colorbar instance.
+    Other Parameters
+    ----------------
+    orientation : {'vertical', 'horizontal'}, default: 'vertical'
+        The orientation of the colorbar.
+
+    %s
     """
 
     orientation = kw.setdefault('orientation', 'vertical')
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -607,8 +607,12 @@ class IndexDateFormatter(ticker.Formatter):
 
     def __init__(self, t, fmt, tz=None):
         """
-        *t* is a sequence of dates (floating point days).  *fmt* is a
-        `~datetime.datetime.strftime` format string.
+        Parameters
+        ----------
+        t : list of float
+            A sequence of dates (floating point days).
+        fmt : str
+            A `~datetime.datetime.strftime` format string.
         """
         if tz is None:
             tz = _get_rc_timezone()
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -941,13 +941,21 @@ def set_bbox_to_anchor(self, bbox, transform=None):
         """
         Set the bbox that the legend will be anchored to.
 
-        *bbox* can be
-
-        - A `.BboxBase` instance
-        - A tuple of ``(left, bottom, width, height)`` in the given transform
-          (normalized axes coordinate if None)
-        - A tuple of ``(left, bottom)`` where the width and height will be
-          assumed to be zero.
+        Parameters
+        ----------
+        bbox : `~matplotlib.transforms.BboxBase` or tuple
+            The bounding box can be specified in the following ways:
+
+            - A `.BboxBase` instance
+            - A tuple of ``(left, bottom, width, height)`` in the given
+              transform (normalized axes coordinate if None)
+            - A tuple of ``(left, bottom)`` where the width and height will be
+              assumed to be zero.
+            - *None*, to remove the bbox anchoring, and use the parent bbox.
+
+        transform : `~matplotlib.transforms.Transform`, optional
+            A transform to apply to the bounding box. If not specified, this
+            will use a transform to the bounding box of the parent.
         """
         if bbox is None:
             self._bbox_to_anchor = None
@@ -978,13 +986,16 @@ def _get_anchored_bbox(self, loc, bbox, parentbbox, renderer):
         Place the *bbox* inside the *parentbbox* according to a given
         location code. Return the (x, y) coordinate of the bbox.
 
-        - loc: a location code in range(1, 11).
-          This corresponds to the possible values for self._loc, excluding
-          "best".
+        Parameters
+        ----------
+        loc : int
+            A location code in range(1, 11). This corresponds to the possible
+            values for ``self._loc``, excluding "best".
+        bbox : `~matplotlib.transforms.Bbox`
+            bbox to be placed, in display coordinates.
+        parentbbox : `~matplotlib.transforms.Bbox`
+            A parent box which will contain the bbox, in display coordinates.
 
-        - bbox: bbox to be placed, display coordinate units.
-        - parentbbox: a parent box which will contain the bbox. In
-            display coordinates.
         """
         assert loc in range(1, 11)  # called only internally
 
@@ -1079,8 +1090,9 @@ def set_draggable(self, state, use_blit=False, update='loc'):
 
         Returns
         -------
-        If *state* is ``True`` this returns the `~.DraggableLegend` helper
-        instance. Otherwise this returns ``None``.
+        `.DraggableLegend` or *None*
+            If *state* is ``True`` this returns the `.DraggableLegend` helper
+            instance. Otherwise this returns *None*.
         """
         if state:
             if self._draggable is None:
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -1493,8 +1493,12 @@ def process_selected(self, ind, xs, ys):
         Default "do nothing" implementation of the
         :meth:`process_selected` method.
 
-        *ind* are the indices of the selected vertices.  *xs* and *ys*
-        are the coordinates of the selected vertices.
+        Parameters
+        ----------
+        ind : list of int
+            The indices of the selected vertices.
+        xs, ys : array-like
+            The coordinates of the selected vertices.
         """
         pass
 
diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py
@@ -142,10 +142,15 @@ def _get_aligned_offsets(hd_list, height, align="baseline"):
     *mode*. xdescent is analogous to the usual descent, but along the
     x-direction. xdescent values are currently ignored.
 
-    *hd_list* : list of (width, xdescent) of boxes to be aligned.
-    *sep* : spacing between boxes
-    *height* : Intended total length. None if not used.
-    *align* : align mode. 'baseline', 'top', 'bottom', or 'center'.
+    Parameters
+    ----------
+    hd_list
+        List of (height, xdescent) of boxes to be aligned.
+    height : float or None
+        Intended total length. If None, the maximum of the heights in *hd_list*
+        is used.
+    align : {'baseline', 'left', 'top', 'right', 'bottom', 'center'}
+        Align mode.
     """
 
     if height is None:
diff --git a/lib/matplotlib/sankey.py b/lib/matplotlib/sankey.py
