From 436e9e596a1ba5b6be3c2e20011f5dc8469a152a Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Wed, 31 Jan 2024 11:26:17 +0000
Subject: [PATCH 1/8] fix "args" use.

---
 benchmarks/benchmarks/generate_data/ugrid.py     | 14 ++++++++------
 docs/gallery_code/general/plot_SOI_filtering.py  |  9 ++++-----
 docs/gallery_code/meteorology/plot_wind_barbs.py |  1 +
 3 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/benchmarks/benchmarks/generate_data/ugrid.py b/benchmarks/benchmarks/generate_data/ugrid.py
index 0ac349d882..713e5dc7df 100644
--- a/benchmarks/benchmarks/generate_data/ugrid.py
+++ b/benchmarks/benchmarks/generate_data/ugrid.py
@@ -24,9 +24,11 @@ def generate_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool, output_path:
     Instead, it is to be called via benchmarks.remote_data_generation,
     so that it can use up-to-date facilities, independent of the ASV controlled
     environment which contains the "Iris commit under test".
+
     This means:
-      * it must be completely self-contained : i.e. it includes all its
-        own imports, and saves results to an output file.
+
+    * it must be completely self-contained : i.e. it includes all its
+      own imports, and saves results to an output file.
 
     """
     from iris import save
@@ -109,8 +111,9 @@ def make_cube_like_umfield(xy_dims):
     Note: probably a bit over-simplified, as there is no time coord, but that
     is probably equally true of our LFRic-style synthetic data.
 
-    Args:
-    * xy_dims (2-tuple):
+    Parameters
+    ----------
+    xy_dims : 2-tuple
         Set the horizontal dimensions = n-lats, n-lons.
 
     """
@@ -165,8 +168,7 @@ def make_cubesphere_testfile(c_size, n_levels=0, n_times=1):
     If n_levels > 0 specified: 3d file with the specified number of levels.
     Return the file path.
 
-    todo: is create_file__xios... still appropriate now we can properly save
-     Mesh Cubes?
+    TODO: is create_file__xios... still appropriate now we can properly save Mesh Cubes?
 
     """
     n_faces = 6 * c_size * c_size
diff --git a/docs/gallery_code/general/plot_SOI_filtering.py b/docs/gallery_code/general/plot_SOI_filtering.py
index 32fe7c6ff7..4b256c894c 100644
--- a/docs/gallery_code/general/plot_SOI_filtering.py
+++ b/docs/gallery_code/general/plot_SOI_filtering.py
@@ -30,12 +30,11 @@
 def low_pass_weights(window, cutoff):
     """Calculate weights for a low pass Lanczos filter.
 
-    Args:
-
-    window: int
+    Parameters
+    ----------
+    window : int
         The length of the filter window.
-
-    cutoff: float
+    cutoff : float
         The cutoff frequency in inverse time steps.
 
     """
diff --git a/docs/gallery_code/meteorology/plot_wind_barbs.py b/docs/gallery_code/meteorology/plot_wind_barbs.py
index 4126d1f995..f11c9a7b50 100644
--- a/docs/gallery_code/meteorology/plot_wind_barbs.py
+++ b/docs/gallery_code/meteorology/plot_wind_barbs.py
@@ -9,6 +9,7 @@
 The magnitude of the wind in the original data is low and so doesn't illustrate
 the full range of barbs. The wind is scaled to simulate a storm that better
 illustrates the range of barbs that are available.
+
 """  # noqa: D205, D212, D400
 
 import matplotlib.pyplot as plt

From 957601ae7828291839e58aba15642ed511d9d671 Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Wed, 31 Jan 2024 11:39:36 +0000
Subject: [PATCH 2/8] ensure kwargs parameter is consistent

---
 lib/iris/_constraints.py          |  2 +-
 lib/iris/analysis/__init__.py     | 36 +++++++++++++++----------------
 lib/iris/analysis/_grid_angles.py |  2 +-
 lib/iris/cube.py                  |  6 +++---
 lib/iris/plot.py                  |  2 +-
 5 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/lib/iris/_constraints.py b/lib/iris/_constraints.py
index 1d81cd603b..4c993885a8 100644
--- a/lib/iris/_constraints.py
+++ b/lib/iris/_constraints.py
@@ -40,7 +40,7 @@ def __init__(self, name=None, cube_func=None, coord_values=None, **kwargs):
         coord_values : dict or None, optional
             If a dict, it must map coordinate name to the condition on the
             associated coordinate.
-        **kwargs :
+        ***kwargs : dict, optional
             The remaining keyword arguments are converted to coordinate
             constraints. The name of the argument gives the name of a
             coordinate, and the value of the argument is the condition to meet
diff --git a/lib/iris/analysis/__init__.py b/lib/iris/analysis/__init__.py
index 91bb5b94a4..b9bb0c13b9 100644
--- a/lib/iris/analysis/__init__.py
+++ b/lib/iris/analysis/__init__.py
@@ -515,7 +515,7 @@ def lazy_aggregate(self, data, axis, **kwargs):
             The dimensions to aggregate over -- note that this is defined
             differently to the 'aggregate' method 'axis' argument, which only
             accepts a single dimension index.
-        **kwargs :
+        **kwargs : dict, optional
             All keyword arguments are passed through to the data aggregation
             function.
 
@@ -555,7 +555,7 @@ def aggregate(self, data, axis, **kwargs):
             mdtol.  mdtol=0 means no missing data is tolerated while mdtol=1
             will return the resulting value from the aggregation function.
             Defaults to 1.
-        **kwargs :
+        **kwargs : dict, optional
             All keyword arguments apart from those specified above, are
             passed through to the data aggregation function.
 
@@ -593,7 +593,7 @@ def update_metadata(self, cube, coords, **kwargs):
             Source cube that requires metadata update.
         coords : :class:`iris.coords.Coord`
             The one or more coordinates that were aggregated.
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords (for example, the "ddof"
             keyword for a standard deviation aggregator).
@@ -617,7 +617,7 @@ def post_process(self, collapsed_cube, data_result, coords, **kwargs):
             Result from :func:`iris.analysis.Aggregator.aggregate`
         coords :
             The one or more coordinates that were aggregated over.
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords (for example, the "ddof"
             keyword from a standard deviation aggregator).
@@ -635,7 +635,7 @@ def aggregate_shape(self, **kwargs):
 
         Parameters
         ----------
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords.
 
@@ -684,7 +684,7 @@ def __init__(self, units_func=None, **kwargs):
             value that can be made into one.
             To ensure backwards-compatibility, also accepts a callable with
             call signature (units).
-        **kwargs :
+        **kwargs : dict, optional
             Passed through to :data:`call_func`, :data:`lazy_func`, and
             :data:`units_func`.
 
@@ -737,7 +737,7 @@ def aggregate(self, data, axis, **kwargs):
             mdtol.  mdtol=0 means no missing data is tolerated while mdtol=1
             will return the resulting value from the aggregation function.
             Defaults to 1.
-        **kwargs :
+        **kwargs : dict, optional
             All keyword arguments apart from those specified above, are
             passed through to the data aggregation function.
 
@@ -767,7 +767,7 @@ def lazy_aggregate(self, data, axis, **kwargs):
             The dimensions to aggregate over -- note that this is defined
             differently to the 'aggregate' method 'axis' argument, which only
             accepts a single dimension index.
-        **kwargs :
+        **kwargs : dict, optional
             All keyword arguments are passed through to the data aggregation
             function.
 
@@ -789,7 +789,7 @@ def post_process(self, collapsed_cube, data_result, coords, **kwargs):
             Result from :func:`iris.analysis.Aggregator.aggregate`
         coords :
             The one or more coordinates that were aggregated over.
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords (for example, the "percent"
             keywords from a percentile aggregator).
@@ -844,7 +844,7 @@ def aggregate_shape(self, **kwargs):
 
         Parameters
         ----------
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords.
 
@@ -914,7 +914,7 @@ def __init__(self, units_func=None, lazy_func=None, **kwargs):
             An alternative to :data:`call_func` implementing a lazy
             aggregation. Note that, it need not support all features of the
             main operation, but should raise an error in unhandled cases.
-        **kwargs :
+        **kwargs : dict, optional
             Passed through to :data:`call_func`, :data:`lazy_func`, and
             :data:`units_func`.
 
@@ -958,7 +958,7 @@ def post_process(self, collapsed_cube, data_result, coords, **kwargs):
             Result from :func:`iris.analysis.Aggregator.aggregate`
         coords :
             The one or more coordinates that were aggregated over.
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords (for example, the "weights"
             keyword).
@@ -998,7 +998,7 @@ def update_metadata(self, cube, coords, **kwargs):
             Source cube that requires metadata update.
         coords : :class:`iris.coords.Coord`
             The one or more coordinates that were aggregated.
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords (for example, the "ddof"
             keyword for a standard deviation aggregator).
@@ -1064,7 +1064,7 @@ def __init__(
             An alternative to :data:`call_func` implementing a lazy
             aggregation. Note that, it need not support all features of the
             main operation, but should raise an error in unhandled cases.
-        **kwargs :
+        **kwargs : dict, optional
             Passed through to :data:`call_func`, :data:`lazy_func`, and
             :data:`units_func`.
 
@@ -1086,7 +1086,7 @@ def uses_weighting(self, **kwargs):
 
         Parameters
         ----------
-        **kwargs :
+        **kwargs : dict, optional
             Arguments to filter of weighted keywords.
 
         Returns
@@ -1114,7 +1114,7 @@ def post_process(self, collapsed_cube, data_result, coords, **kwargs):
             Result from :func:`iris.analysis.Aggregator.aggregate`
         coords :
             The one or more coordinates that were aggregated over.
-        **kwargs :
+        **kwargs : dict, optional
             This function is intended to be used in conjunction with aggregate()
             and should be passed the same keywords (for example, the "weights"
             keywords from a mean aggregator).
@@ -1218,7 +1218,7 @@ def create_weighted_aggregator_fn(aggregator_fn, axis, **kwargs):
     axis : int
         Axis to aggregate over. This argument is directly passed to
         ``aggregator_fn``.
-    **kwargs :
+    **kwargs : dict, optional
         Arbitrary keyword arguments passed to ``aggregator_fn``. Should not
         include ``weights`` (this will be removed if present).
 
@@ -1412,7 +1412,7 @@ def _weighted_quantile_1D(data, weights, quantiles, **kwargs):
         matching mask.
     quantiles : float or sequence of floats
         Quantile(s) to compute. Must have a value between 0 and 1.
-    **kwargs :
+    **kwargs : dict, optional
         passed to `scipy.interpolate.interp1d`
 
     Returns
diff --git a/lib/iris/analysis/_grid_angles.py b/lib/iris/analysis/_grid_angles.py
index 62bf148f45..8712dd9ad1 100644
--- a/lib/iris/analysis/_grid_angles.py
+++ b/lib/iris/analysis/_grid_angles.py
@@ -416,7 +416,7 @@ def rotate_grid_vectors(u_cube, v_cube, grid_angles_cube=None, grid_angles_kwarg
         Units must be angular, i.e. can be converted to 'radians'.
         If not provided, grid angles are estimated from 'u_cube' using the
         :func:`gridcell_angles` method.
-    **grid_angles_kwargs : dict or None
+    **grid_angles_kwargs : dict, optional
         Additional keyword args to be passed to the :func:`gridcell_angles`
         method, if it is used.
 
diff --git a/lib/iris/cube.py b/lib/iris/cube.py
index f868c2a082..fa84815718 100644
--- a/lib/iris/cube.py
+++ b/lib/iris/cube.py
@@ -3962,7 +3962,7 @@ def collapsed(self, coords, aggregator, **kwargs):
             collapsed.
         aggregator : :class:`iris.analysis.Aggregator`
             Aggregator to be applied for collapse operation.
-        **kwargs :
+        **kwargs : dict, optional
             Aggregation function keyword arguments.
 
         Returns
@@ -4202,7 +4202,7 @@ def aggregated_by(self, coords, aggregator, climatological=False, **kwargs):
             any aggregated time coord(s), this causes the climatological flag to
             be set and the point for each cell to equal its first bound, thereby
             preserving the time of year.
-        **kwargs : optional
+        **kwargs : dict, optional
             Aggregator and aggregation function keyword arguments.
 
         Returns
@@ -4466,7 +4466,7 @@ def rolling_window(self, coord, aggregator, window, **kwargs):
             Aggregator to be applied to the data.
         window : int
             Size of window to use.
-        **kwargs : optional
+        **kwargs : dict, optional
             Aggregator and aggregation function keyword arguments. The weights
             argument to the aggregator, if any, should be a 1d array, cube, or
             (names of) :meth:`~iris.cube.Cube.coords`,
diff --git a/lib/iris/plot.py b/lib/iris/plot.py
index a6c1a03b2d..66162f78c0 100644
--- a/lib/iris/plot.py
+++ b/lib/iris/plot.py
@@ -1421,7 +1421,7 @@ def points(cube, *args, **kwargs):
     axes : :class:`matplotlib.axes.Axes`, optional
         The axes to use for drawing.  Defaults to the current axes if none
         provided.
-    **kwargs :dict
+    **kwargs : dict, optional
         See :func:`matplotlib.pyplot.scatter` for details of other valid
         keyword arguments.
 

From 09872a7657b8ce690f508ca09c2820dae1cfd0ae Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Wed, 31 Jan 2024 11:42:40 +0000
Subject: [PATCH 3/8] fix bool type

---
 lib/iris/util.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/iris/util.py b/lib/iris/util.py
index 8c081e3ec0..3b649946eb 100644
--- a/lib/iris/util.py
+++ b/lib/iris/util.py
@@ -579,7 +579,7 @@ def monotonic(array, strict=False, return_direction=False):
 
     Parameters
     ----------
-    strict : boolean, default=False
+    strict : bool, default=False
         Flag to enable strict monotonic checking
     return_direction : bool, default=False
         Flag to change return behaviour to return

From cad892d7b26bc9294cc11641b39bff57559bed14 Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Wed, 31 Jan 2024 11:50:06 +0000
Subject: [PATCH 4/8] default=None not needed in some cases

---
 lib/iris/analysis/maths.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/iris/analysis/maths.py b/lib/iris/analysis/maths.py
index 3dbe98f49d..f20972d1e5 100644
--- a/lib/iris/analysis/maths.py
+++ b/lib/iris/analysis/maths.py
@@ -41,7 +41,7 @@ def _output_dtype(op, first_dtype, second_dtype=None, in_place=False):
         A unary or binary operator which can be applied to array-like objects.
     first_dtype :
         The dtype of the first or only argument to the operator.
-    second_dtype : optional, default=None
+    second_dtype : optional
         The dtype of the second argument to the operator.
     in_place : bool, default=False
         Whether the operation is to be performed in place.
@@ -333,7 +333,7 @@ def _add_subtract_common(
     new_dtype :
         The expected dtype of the output. Used in the case of scalar
         masked arrays
-    dim : optional, default=None
+    dim : optional
         Dimension along which to apply `other` if it's a coordinate that is not
         found in `cube`
     in_place : bool, default=False

From 2ba3085d5f61531aa1874754f96decfa7d7533bd Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Thu, 1 Feb 2024 10:55:18 +0000
Subject: [PATCH 5/8] added note directive

---
 .../general/plot_anomaly_log_colouring.py        | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/docs/gallery_code/general/plot_anomaly_log_colouring.py b/docs/gallery_code/general/plot_anomaly_log_colouring.py
index 16210173c5..cd11161041 100644
--- a/docs/gallery_code/general/plot_anomaly_log_colouring.py
+++ b/docs/gallery_code/general/plot_anomaly_log_colouring.py
@@ -15,13 +15,15 @@
 the matplotlib Norm class :obj:`matplotlib.colors.SymLogNorm`.
 We use this to make a cell-filled pseudocolor plot with a colorbar.
 
-NOTE: By "pseudocolour", we mean that each data point is drawn as a "cell"
-region on the plot, coloured according to its data value.
-This is provided in Iris by the functions :meth:`iris.plot.pcolor` and
-:meth:`iris.plot.pcolormesh`, which call the underlying matplotlib
-functions of the same names (i.e., :obj:`matplotlib.pyplot.pcolor`
-and :obj:`matplotlib.pyplot.pcolormesh`).
-See also: https://en.wikipedia.org/wiki/False_color#Pseudocolor.
+.. note::
+
+    By "pseudocolour", we mean that each data point is drawn as a "cell"
+    region on the plot, coloured according to its data value.
+    This is provided in Iris by the functions :meth:`iris.plot.pcolor` and
+    :meth:`iris.plot.pcolormesh`, which call the underlying matplotlib
+    functions of the same names (i.e., :obj:`matplotlib.pyplot.pcolor`
+    and :obj:`matplotlib.pyplot.pcolormesh`).
+    See also: https://en.wikipedia.org/wiki/False_color#Pseudocolor.
 
 """  # noqa: D205, D212, D400
 

From 925b7db2b239ab1a7fe5252bf308da0659657489 Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Sat, 3 Feb 2024 17:58:05 +0000
Subject: [PATCH 6/8] fix escape chars.

---
 lib/iris/__init__.py                  |  4 ++--
 lib/iris/_concatenate.py              |  2 +-
 lib/iris/analysis/_regrid.py          |  8 ++++----
 lib/iris/cube.py                      | 16 ++++++++--------
 lib/iris/exceptions.py                |  2 +-
 lib/iris/experimental/ugrid/load.py   |  8 ++++----
 lib/iris/experimental/ugrid/mesh.py   | 10 +++++-----
 lib/iris/fileformats/netcdf/loader.py |  4 ++--
 lib/iris/fileformats/netcdf/saver.py  |  2 +-
 lib/iris/pandas.py                    | 10 +++++-----
 10 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/lib/iris/__init__.py b/lib/iris/__init__.py
index 828a507fff..de7ab140ca 100644
--- a/lib/iris/__init__.py
+++ b/lib/iris/__init__.py
@@ -141,7 +141,7 @@ class Future(threading.local):
     """Run-time configuration controller."""
 
     def __init__(self, datum_support=False, pandas_ndim=False, save_split_attrs=False):
-        r"""Container for run-time options controls.
+        """Container for run-time options controls.
 
         To adjust the values simply update the relevant attribute from
         within your code. For example::
@@ -156,7 +156,7 @@ def __init__(self, datum_support=False, pandas_ndim=False, save_split_attrs=Fals
         ----------
         datum_support : bool, default=False
             Opts in to loading coordinate system datum information from NetCDF
-            files into :class:`~iris.coord_systems.CoordSystem`\\ s, wherever
+            files into :class:`~iris.coord_systems.CoordSystem`, wherever
             this information is present.
         pandas_ndim : bool, default=False
             See :func:`iris.pandas.as_data_frame` for details - opts in to the
diff --git a/lib/iris/_concatenate.py b/lib/iris/_concatenate.py
index ea2ba65402..2a73fcacea 100644
--- a/lib/iris/_concatenate.py
+++ b/lib/iris/_concatenate.py
@@ -69,7 +69,7 @@ class _CoordMetaData(
         The points data :class:`np.dtype` of an associated coordinate.
     bounds_dtype : :class:`np.dtype`
         The bounds data :class:`np.dtype` of an associated coordinate.
-    **kwargs :
+    **kwargs : dict, optional
         A dictionary of key/value pairs required to define a coordinate.
 
     """
diff --git a/lib/iris/analysis/_regrid.py b/lib/iris/analysis/_regrid.py
index be3f08278e..4a8ba0bb67 100644
--- a/lib/iris/analysis/_regrid.py
+++ b/lib/iris/analysis/_regrid.py
@@ -993,10 +993,10 @@ def _create_cube(data, src, src_dims, tgt_coords, num_tgt_dims, regrid_callback)
         The source Cube.
     src_dims : tuple of int
         The dimensions of the X and Y coordinate within the source Cube.
-    tgt_coords : tuple of :class:`iris.coords.Coord`\\ 's
-        Either two 1D :class:`iris.coords.DimCoord`\\ 's, two 1D
-        :class:`iris.experimental.ugrid.DimCoord`\\ 's or two n-D
-        :class:`iris.coords.AuxCoord`\\ 's representing the new grid's
+    tgt_coords : tuple of :class:`iris.coords.Coord
+        Either two 1D :class:`iris.coords.DimCoord`, two 1D
+        :class:`iris.experimental.ugrid.DimCoord` or two n-D
+        :class:`iris.coords.AuxCoord` representing the new grid's
         X and Y coordinates.
     num_tgt_dims : int
         The number of dimensions that the `tgt_coords` span.
diff --git a/lib/iris/cube.py b/lib/iris/cube.py
index fa84815718..a6f283100a 100644
--- a/lib/iris/cube.py
+++ b/lib/iris/cube.py
@@ -739,14 +739,14 @@ def _is_single_item(testee):
 
 
 class CubeAttrsDict(MutableMapping):
-    r"""A :class:`dict`\\-like object for :attr:`iris.cube.Cube.attributes`.
+    """A :class:`dict`-like object for :attr:`iris.cube.Cube.attributes`.
 
-    A :class:`dict`\\-like object for :attr:`iris.cube.Cube.attributes`,
+    A :class:`dict`-like object for :attr:`iris.cube.Cube.attributes`,
     providing unified user access to combined cube "local" and "global" attributes
     dictionaries, with the access behaviour of an ordinary (single) dictionary.
 
     Properties :attr:`globals` and :attr:`locals` are regular
-    :class:`~iris.common.mixin.LimitedAttributeDict`\\s, which can be accessed and
+    :class:`~iris.common.mixin.LimitedAttributeDict`, which can be accessed and
     modified separately.  The :class:`CubeAttrsDict` itself contains *no* additional
     state, but simply provides a 'combined' view of both global + local attributes.
 
@@ -2359,7 +2359,7 @@ def mesh(self):
 
         Return the unstructured :class:`~iris.experimental.ugrid.Mesh`
         associated with the cube, if the cube has any
-        :class:`~iris.experimental.ugrid.MeshCoord`\\ s,
+        :class:`~iris.experimental.ugrid.MeshCoord`,
         or ``None`` if it has none.
 
         Returns
@@ -2380,14 +2380,14 @@ def location(self):
         r"""Return the mesh "location" of the cube data.
 
         Return the mesh "location" of the cube data, if the cube has any
-        :class:`~iris.experimental.ugrid.MeshCoord`\\ s,
+        :class:`~iris.experimental.ugrid.MeshCoord`,
         or ``None`` if it has none.
 
         Returns
         -------
         location : str or None
             The mesh location of the cube
-            :class:`~iris.experimental.ugrid.MeshCoord`'s
+            :class:`~iris.experimental.ugrid.MeshCoords`
             (i.e. one of 'face' / 'edge' / 'node'), or ``None``.
 
         """
@@ -2400,14 +2400,14 @@ def mesh_dim(self):
         r"""Return the cube dimension of the mesh.
 
         Return the cube dimension of the mesh, if the cube has any
-        :class:`~iris.experimental.ugrid.MeshCoord`\\ s,
+        :class:`~iris.experimental.ugrid.MeshCoord`,
         or ``None`` if it has none.
 
         Returns
         -------
         mesh_dim : int or None
             The cube dimension which the cube
-            :class:`~iris.experimental.ugrid.MeshCoord`\\s map to,
+            :class:`~iris.experimental.ugrid.MeshCoord` map to,
             or ``None``.
 
         """
diff --git a/lib/iris/exceptions.py b/lib/iris/exceptions.py
index 854785ef56..0fb06f3b26 100644
--- a/lib/iris/exceptions.py
+++ b/lib/iris/exceptions.py
@@ -169,7 +169,7 @@ class CannotAddError(ValueError):
 
 
 class IrisUserWarning(UserWarning):
-    r"""Base class for :class:`UserWarning`\\ s generated by Iris."""
+    r"""Base class for :class:`UserWarning` generated by Iris."""
 
     pass
 
diff --git a/lib/iris/experimental/ugrid/load.py b/lib/iris/experimental/ugrid/load.py
index b431f1ca96..8ba7448e8c 100644
--- a/lib/iris/experimental/ugrid/load.py
+++ b/lib/iris/experimental/ugrid/load.py
@@ -3,10 +3,10 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 
-r"""Allow the construction of :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es.
+r"""Allow the construction of :class:`~iris.experimental.ugrid.mesh.Mesh`.
 
 Extensions to Iris' NetCDF loading to allow the construction of
-:class:`~iris.experimental.ugrid.mesh.Mesh`\\ es from UGRID data in the file.
+:class:`~iris.experimental.ugrid.mesh.Mesh` from UGRID data in the file.
 
 Eventual destination: :mod:`iris.fileformats.netcdf`.
 
@@ -155,7 +155,7 @@ def load_meshes(uris, var_name=None):
         One or more filenames/URI's. Filenames can include wildcards. Any URI's
         must support OpenDAP.
     var_name : str, optional
-        Only return :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es that have
+        Only return :class:`~iris.experimental.ugrid.mesh.Mesh` that have
         var_names matching this value.
 
     Returns
@@ -163,7 +163,7 @@ def load_meshes(uris, var_name=None):
     dict
         A dictionary mapping each mesh-containing file path/URL in the input
         ``uris`` to a list of the
-        :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es returned from each.
+        :class:`~iris.experimental.ugrid.mesh.Mesh` returned from each.
 
     """
     # TODO: rationalise UGRID/mesh handling once experimental.ugrid is folded
diff --git a/lib/iris/experimental/ugrid/mesh.py b/lib/iris/experimental/ugrid/mesh.py
index 2494998e4c..a2519f250b 100644
--- a/lib/iris/experimental/ugrid/mesh.py
+++ b/lib/iris/experimental/ugrid/mesh.py
@@ -693,7 +693,7 @@ def normalise(element, axis):
 
     @classmethod
     def from_coords(cls, *coords):
-        r"""Construct a :class:`Mesh` by derivation from one or more :class:`~iris.coords.Coord`\\ s.
+        r"""Construct a :class:`Mesh` by derivation from one or more :class:`~iris.coords.Coord`.
 
         The :attr:`~Mesh.topology_dimension`, :class:`~iris.coords.Coord`
         membership and :class:`Connectivity` membership are all determined
@@ -734,9 +734,9 @@ def from_coords(cls, *coords):
 
         .. note::
             :class:`Mesh` currently requires ``X`` and ``Y``
-            :class:`~iris.coords.Coord`\\ s specifically.
+            :class:`~iris.coords.Coord` specifically.
             :meth:`iris.util.guess_coord_axis` is therefore attempted, else the
-            first two :class:`~iris.coords.Coord`\\ s are taken.
+            first two :class:`~iris.coords.Coord` are taken.
 
         .. testsetup::
 
@@ -1869,10 +1869,10 @@ def to_MeshCoord(self, location, axis):
         return MeshCoord(mesh=self, location=location, axis=axis)
 
     def to_MeshCoords(self, location):
-        r"""Generate a tuple of :class:`~iris.experimental.ugrid.mesh.MeshCoord`\\ s.
+        r"""Generate a tuple of :class:`~iris.experimental.ugrid.mesh.MeshCoord`.
 
         Generate a tuple of
-        :class:`~iris.experimental.ugrid.mesh.MeshCoord`\\ s, each referencing
+        :class:`~iris.experimental.ugrid.mesh.MeshCoord`, each referencing
         the current :class:`Mesh`, one for each :attr:`AXES` value, passing
         through the ``location`` argument.
 
diff --git a/lib/iris/fileformats/netcdf/loader.py b/lib/iris/fileformats/netcdf/loader.py
index 1dcf026d84..42b6ee509c 100644
--- a/lib/iris/fileformats/netcdf/loader.py
+++ b/lib/iris/fileformats/netcdf/loader.py
@@ -706,7 +706,7 @@ def set(
         ----------
         var_names : str or list of str, default=None
             apply the `dimension_chunksizes` controls only to these variables,
-            or when building :class:`~iris.cube.Cube`\\ s from these data variables.
+            or when building :class:`~iris.cube.Cube` from these data variables.
             If ``None``, settings apply to all loaded variables.
         dimension_chunksizes : dict of {str: int}
             Kwargs specifying chunksizes for dimensions of file variables.
@@ -777,7 +777,7 @@ def from_file(self) -> None:
         ------
         KeyError
             If any NetCDF data variables - those that become
-            :class:`~iris.cube.Cube`\\ s - do not specify chunk sizes.
+            :class:`~iris.cube.Cube` - do not specify chunk sizes.
 
         Notes
         -----
diff --git a/lib/iris/fileformats/netcdf/saver.py b/lib/iris/fileformats/netcdf/saver.py
index a607d7de97..086732e597 100644
--- a/lib/iris/fileformats/netcdf/saver.py
+++ b/lib/iris/fileformats/netcdf/saver.py
@@ -2592,7 +2592,7 @@ def save(
 
     * Iris will write CF 1.7 compliant NetCDF files.
     * **If split-attribute saving is disabled**, i.e.
-      :data:`iris.FUTURE`\\ ``.save_split_attrs`` is ``False``, then attributes
+      :data:`iris.FUTURE` ``.save_split_attrs`` is ``False``, then attributes
       dictionaries on each cube in the saved cube list will be compared, and common
       attributes saved as NetCDF global attributes where appropriate.
 
diff --git a/lib/iris/pandas.py b/lib/iris/pandas.py
index 0c75208bd0..d60b46011e 100644
--- a/lib/iris/pandas.py
+++ b/lib/iris/pandas.py
@@ -195,7 +195,7 @@ def as_cubes(
     r"""Convert a Pandas Series/DataFrame into n-dimensional Iris Cubes, including dimensional metadata.
 
     The index of `pandas_structure` will be used for generating the
-    :class:`~iris.cube.Cube` dimension(s) and :class:`~iris.coords.DimCoord`\\ s.
+    :class:`~iris.cube.Cube` dimension(s) and :class:`~iris.coords.DimCoord`.
     Other dimensional metadata may span multiple dimensions - based on how the
     column values vary with the index values.
 
@@ -227,7 +227,7 @@ def as_cubes(
     A :class:`~pandas.DataFrame` using columns as a second data dimension will
     need to be 'melted' before conversion. See the Examples for how.
 
-    :class:`dask.dataframe.DataFrame`\\ s are not supported.
+    :class:`dask.dataframe.DataFrame` are not supported.
 
     Since this function converts to/from a Pandas object, laziness will not be preserved.
 
@@ -303,7 +303,7 @@ def as_cubes(
             in_region                             x            x          -
 
     Pandas uses ``NaN`` rather than masking data. Converted
-    :class:`~iris.cube.Cube`\\s can be masked in downstream user code :
+    :class:`~iris.cube.Cube` can be masked in downstream user code :
 
     >>> my_series = Series([300, np.NaN, 302], name="air_temperature")
     >>> converted_cube = as_cubes(my_series)[0]
@@ -651,7 +651,7 @@ def as_data_frame(
     #. This documentation is for the new ``as_data_frame()`` behaviour, which
        is **currently opt-in** to preserve backwards compatibility. The default
        legacy behaviour is documented in pre-``v3.4`` documentation (summary:
-       limited to 2-dimensional :class:`~iris.cube.Cube`\\ s, with only the
+       limited to 2-dimensional :class:`~iris.cube.Cube`, with only the
        :attr:`~iris.cube.Cube.data` and :attr:`~iris.cube.Cube.dim_coords`
        being added). The legacy behaviour will be removed in a future version
        of Iris, so please opt-in to the new behaviour at your earliest
@@ -671,7 +671,7 @@ def as_data_frame(
 
     Notes
     -----
-    :class:`dask.dataframe.DataFrame`\\ s are not supported.
+    :class:`dask.dataframe.DataFrame` are not supported.
 
     A :class:`~pandas.MultiIndex` :class:`~pandas.DataFrame` is returned by default.
     Use the :meth:`~pandas.DataFrame.reset_index` to return a

From 73863a1e8688ab73bcad1a69f301e5d0bcdd0ce3 Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Sat, 3 Feb 2024 18:43:05 +0000
Subject: [PATCH 7/8] misc docstring formatting.

---
 lib/iris/__init__.py    |  4 ++--
 lib/iris/coords.py      |  2 ++
 lib/iris/io/__init__.py | 12 ++++++------
 lib/iris/plot.py        | 30 +++++++++++++-----------------
 lib/iris/symbols.py     |  4 ++--
 5 files changed, 25 insertions(+), 27 deletions(-)

diff --git a/lib/iris/__init__.py b/lib/iris/__init__.py
index de7ab140ca..f0421e9662 100644
--- a/lib/iris/__init__.py
+++ b/lib/iris/__init__.py
@@ -72,9 +72,9 @@
 
     1. Function signature must be: ``(cube, field, filename)``.
     2. Modifies the given cube inplace, unless a new cube is
-        returned by the function.
+       returned by the function.
     3. If the cube is to be rejected the callback must raise
-        an :class:`iris.exceptions.IgnoreCubeException`.
+       an :class:`iris.exceptions.IgnoreCubeException`.
 
     For example::
 
diff --git a/lib/iris/coords.py b/lib/iris/coords.py
index a9eae6e2ac..8cbe0984cd 100644
--- a/lib/iris/coords.py
+++ b/lib/iris/coords.py
@@ -1512,6 +1512,8 @@ def __init__(
     def copy(self, points=None, bounds=None):
         """Return a copy of this coordinate.
 
+        Parameters
+        ----------
         points : optional
             A points array for the new coordinate.
             This may be a different shape to the points of the coordinate
diff --git a/lib/iris/io/__init__.py b/lib/iris/io/__init__.py
index 2b667cfab6..d5896f25a4 100644
--- a/lib/iris/io/__init__.py
+++ b/lib/iris/io/__init__.py
@@ -381,12 +381,12 @@ def save(source, target, saver=None, **kwargs):
     Iris currently supports three file formats for saving, which it can
     recognise by filename extension:
 
-    * netCDF - the Unidata network Common Data Format:
-        * see :func:`iris.fileformats.netcdf.save`
-    * GRIB2 - the WMO GRIdded Binary data format:
-        * see :func:`iris_grib.save_grib2`.
-    * PP - the Met Office UM Post Processing Format:
-        * see :func:`iris.fileformats.pp.save`
+    * **netCDF** - the Unidata network Common Data Format,
+      see :func:`iris.fileformats.netcdf.save`
+    * **GRIB2** - the WMO GRIdded Binary data format,
+      see :func:`iris_grib.save_grib2`.
+    * **PP** - the Met Office UM Post Processing Format,
+      see :func:`iris.fileformats.pp.save`
 
     A custom saver can be provided to the function to write to a different
     file format.
diff --git a/lib/iris/plot.py b/lib/iris/plot.py
index 66162f78c0..c727607449 100644
--- a/lib/iris/plot.py
+++ b/lib/iris/plot.py
@@ -1845,29 +1845,25 @@ def animate(cube_iterator, plot_func, fig=None, **kwargs):
     fig : :class:`matplotlib.figure.Figure` instance, optional
         By default, the current figure will be used or a new figure instance
         created if no figure is available. See :func:`matplotlib.pyplot.gcf`.
+    coords: list of :class:`~iris.coords.Coord` objects or coordinate names, optional
+        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.
+    interval: int, float or long, optional
+        Defines the time interval in milliseconds between successive frames.
+        A default interval of 100ms is set.
+    vmin, vmax: int, float or long, optional
+        Color scaling values, see :class:`matplotlib.colors.Normalize` for
+        further details. Default values are determined by the min-max across
+        the data set over the entire sequence.
     **kwargs : dict, optional
-        Valid keyword arguments:
-
-        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.
-        interval: int, float or long
-            Defines the time interval in milliseconds between successive frames.
-            A default interval of 100ms is set.
-        vmin, vmax: int, float or long
-            Color scaling values, see :class:`matplotlib.colors.Normalize` for
-            further details. Default values are determined by the min-max across
-            the data set over the entire sequence.
-
         See :class:`matplotlib.animation.FuncAnimation` for details of other
         valid keyword arguments.
 
     Returns
     -------
-    :class:`~matplotlib.animation.FuncAnimation` object suitable for
-    saving and or plotting.
+    :class:`~matplotlib.animation.FuncAnimation` object suitable for saving and or plotting.
 
     Examples
     --------
diff --git a/lib/iris/symbols.py b/lib/iris/symbols.py
index 4e66daa100..e52266b2fe 100644
--- a/lib/iris/symbols.py
+++ b/lib/iris/symbols.py
@@ -227,8 +227,8 @@ def _wedge_fix(wedge_path):
 A dictionary mapping WMO cloud cover codes to their corresponding symbol.
 
 See https://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf
-    Part II, Appendix II.4, Graphical Representation of Data, Analyses
-    and Forecasts
+Part II, Appendix II.4, Graphical Representation of Data, Analyses
+and Forecasts
 
 """
 

From 5e39fcc3feddf69030b2086f4bfc5fe6ab962c59 Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Mon, 5 Feb 2024 09:50:55 +0000
Subject: [PATCH 8/8] removed defunct IMPORT_LOGGER

---
 lib/iris/config.py | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/lib/iris/config.py b/lib/iris/config.py
index 6e350a456d..c617783dec 100644
--- a/lib/iris/config.py
+++ b/lib/iris/config.py
@@ -21,10 +21,6 @@
 
     The full path to the Iris palette configuration directory
 
-.. py:data:: iris.config.IMPORT_LOGGER
-
-    The [optional] name of the logger to notify when first imported.
-
 ----------
 
 """