diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 808f1de421..250ac143c7 100644 --- a/docs/src/whatsnew/latest.rst +++ b/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 =========== diff --git a/lib/iris/plot.py b/lib/iris/plot.py index bda5274cca..c5c3a2745f 100644 --- a/lib/iris/plot.py +++ b/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. """