separate arg types from descriptions (#4100)

Author: rcomer

docs/src/whatsnew/latest.rst

@@ -116,6 +116,10 @@ This document explains the changes made to Iris for this release
 #. `@bjlittle`_ added the |pre-commit.ci|_ badge to the `README.md`_.
    See :ref:`pre_commit_ci` for further details. (:pull:`4061`)
 
+#. `@rcomer`_ tweaked docstring layouts in the :mod:`iris.plot` module, so
+   they render better in the published documentation.  See :issue:`4085`.
+   (:pull:`4100`)
+
 
 💼 Internal
 ===========

lib/iris/plot.py

@@ -1014,15 +1014,16 @@ def contour(cube, *args, **kwargs):
 
     Kwargs:
 
-    * coords: list of :class:`~iris.coords.Coord` objects or
-        coordinate names. Use the given coordinates as the axes for the
+    * coords: list of :class:`~iris.coords.Coord` objects or coordinate names
+        Use the given coordinates as the axes for the
         plot. The order of the given coordinates indicates which axis
         to use for each, where the first element is the horizontal
         axis of the plot and the second element is the vertical axis
         of the plot.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     See :func:`matplotlib.pyplot.contour` for details of other valid
     keyword arguments.
@@ -1038,15 +1039,15 @@ def contourf(cube, *args, **kwargs):
 
     Kwargs:
 
-    * coords: list of :class:`~iris.coords.Coord` objects or
-        coordinate names. Use the given coordinates as the axes for the
-        plot. The order of the given coordinates indicates which axis
-        to use for each, where the first element is the horizontal
-        axis of the plot and the second element is the vertical axis
-        of the plot.
+    * coords: list of :class:`~iris.coords.Coord` objects or coordinate names
+        Use the given coordinates as the axes for the plot. The order of the
+        given coordinates indicates which axis to use for each, where the first
+        element is the horizontal axis of the plot and the second element is
+        the vertical axis of the plot.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     See :func:`matplotlib.pyplot.contourf` for details of other valid
     keyword arguments.
@@ -1127,10 +1128,10 @@ def default_projection_extent(cube, mode=iris.coords.POINT_MODE):
 
     Keyword arguments:
 
-     * mode - Either ``iris.coords.POINT_MODE`` or ``iris.coords.BOUND_MODE``.
-              Triggers whether the extent should be representative of the cell
-              points, or the limits of the cell's bounds.
-              The default is iris.coords.POINT_MODE.
+    * mode: Either ``iris.coords.POINT_MODE`` or ``iris.coords.BOUND_MODE``
+            Triggers whether the extent should be representative of the cell
+            points, or the limits of the cell's bounds.
+            The default is iris.coords.POINT_MODE.
 
     """
     extents = cartography._xy_range(cube, mode)
@@ -1229,23 +1230,24 @@ def outline(cube, coords=None, color="k", linewidth=None, axes=None):
 
     Kwargs:
 
-    * coords: list of :class:`~iris.coords.Coord` objects or
-        coordinate names. Use the given coordinates as the axes for the
+    * coords: list of :class:`~iris.coords.Coord` objects or coordinate names
+        Use the given coordinates as the axes for the
         plot. The order of the given coordinates indicates which axis
         to use for each, where the first element is the horizontal
         axis of the plot and the second element is the vertical axis
         of the plot.
 
-    * color: None or mpl color The color of the cell outlines. If
-        None, the matplotlibrc setting patch.edgecolor is used by
-        default.
+    * color: None or mpl color
+        The color of the cell outlines. If None, the matplotlibrc setting
+        patch.edgecolor is used by default.
 
-    * linewidth: None or number The width of the lines showing the
-        cell outlines. If None, the default width in patch.linewidth
-        in matplotlibrc is used.
+    * linewidth: None or number
+        The width of the lines showing the cell outlines. If None, the default
+        width in patch.linewidth in matplotlibrc is used.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     """
     result = _draw_2d_from_bounds(
@@ -1276,18 +1278,20 @@ def pcolor(cube, *args, **kwargs):
 
     Kwargs:
 
-    * coords: list of :class:`~iris.coords.Coord` objects or
-        coordinate names. Use the given coordinates as the axes for the
+    * coords: list of :class:`~iris.coords.Coord` objects or coordinate names
+        Use the given coordinates as the axes for the
         plot. The order of the given coordinates indicates which axis
         to use for each, where the first element is the horizontal
         axis of the plot and the second element is the vertical axis
         of the plot.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
-    * contiguity_tolerance: The absolute tolerance used when checking for
-        contiguity between the bounds of the cells. Defaults to None.
+    * contiguity_tolerance: float
+        The absolute tolerance used when checking for contiguity between the
+        bounds of the cells. Defaults to None.
 
     See :func:`matplotlib.pyplot.pcolor` for details of other valid
     keyword arguments.
@@ -1309,17 +1313,18 @@ def pcolormesh(cube, *args, **kwargs):
 
     Kwargs:
 
-    * coords: list of :class:`~iris.coords.Coord` objects or
-        coordinate names. Use the given coordinates as the axes for the
-        plot. The order of the given coordinates indicates which axis
-        to use for each, where the first element is the horizontal
-        axis of the plot and the second element is the vertical axis
-        of the plot.
+    * coords: list of :class:`~iris.coords.Coord` objects or coordinate names
+        Use the given coordinates as the axes for the plot. The order of the
+        given coordinates indicates which axis to use for each, where the first
+        element is the horizontal axis of the plot and the second element is
+        the vertical axis of the plot.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
-    * contiguity_tolerance: The absolute tolerance used when checking for
+    * contiguity_tolerance: float
+        The absolute tolerance used when checking for
         contiguity between the bounds of the cells. Defaults to None.
 
     See :func:`matplotlib.pyplot.pcolormesh` for details of other
@@ -1336,15 +1341,16 @@ def points(cube, *args, **kwargs):
 
     Kwargs:
 
-    * coords: list of :class:`~iris.coords.Coord` objects or
-        coordinate names. Use the given coordinates as the axes for the
+    * coords: list of :class:`~iris.coords.Coord` objects or coordinate names
+        Use the given coordinates as the axes for the
         plot. The order of the given coordinates indicates which axis
         to use for each, where the first element is the horizontal
         axis of the plot and the second element is the vertical axis
         of the plot.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     See :func:`matplotlib.pyplot.scatter` for details of other valid
     keyword arguments.
@@ -1406,7 +1412,7 @@ def quiver(u_cube, v_cube, *args, **kwargs):
 
     Args:
 
-    * u_cube, v_cube : (:class:`~iris.cube.Cube`)
+    * u_cube, v_cube : :class:`~iris.cube.Cube`
         u and v vector components.  Must have same shape and units.
         If the cubes have geographic coordinates, the values are treated as
         true distance differentials, e.g. windspeeds, and *not* map coordinate
@@ -1425,15 +1431,16 @@ def quiver(u_cube, v_cube, *args, **kwargs):
 
     Kwargs:
 
-    * coords: (list of :class:`~iris.coords.Coord` or string)
+    * coords: list of :class:`~iris.coords.Coord` or string
         Coordinates or coordinate names. Use the given coordinates as the axes
         for the plot. The order of the given coordinates indicates which axis
         to use for each, where the first element is the horizontal
         axis of the plot and the second element is the vertical axis
         of the plot.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     See :func:`matplotlib.pyplot.quiver` for details of other valid
     keyword arguments.
@@ -1477,8 +1484,9 @@ def plot(*args, **kwargs):
 
     Kwargs:
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     See :func:`matplotlib.pyplot.plot` for details of additional valid
     keyword arguments.
@@ -1508,8 +1516,9 @@ def scatter(x, y, *args, **kwargs):
 
     Kwargs:
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     See :func:`matplotlib.pyplot.scatter` for details of additional
     valid keyword arguments.
@@ -1551,8 +1560,9 @@ def symbols(x, y, symbols, size, axes=None, units="inches"):
 
     Kwargs:
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     * units: ['inches', 'points']
         The unit for the symbol size.
@@ -1604,17 +1614,17 @@ def citation(text, figure=None, axes=None):
 
     Args:
 
-    * text:
+    * text: str
         Citation text to be plotted.
 
     Kwargs:
 
-    * figure:
-        Target :class:`matplotlib.figure.Figure` instance. Defaults
-        to the current figure if none provided.
+    * figure::class:`matplotlib.figure.Figure`
+        Target figure instance. Defaults to the current figure if none provided.
 
-    * axes: the :class:`matplotlib.axes.Axes` to use for drawing.
-        Defaults to the current axes if none provided.
+    * axes: :class:`matplotlib.axes.Axes`
+        The axes to use for drawing.  Defaults to the current axes if none
+        provided.
 
     """