Skip to content

iris.plot docstrings: separate arg types from descriptions #4100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 6, 2021
Merged

iris.plot docstrings: separate arg types from descriptions #4100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/src/whatsnew/latest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
===========
Expand Down
132 changes: 71 additions & 61 deletions lib/iris/plot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

"""

Expand Down