Numpydocs misc (#5728)

* fix "args" use.

* ensure kwargs parameter is consistent

* fix bool type

* default=None not needed in some cases

* added note directive

* fix escape chars.

* misc docstring formatting.

* removed defunct IMPORT_LOGGER

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

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.
 
     """

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
 

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

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::
 
@@ -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

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.
 
     """

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

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

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.
 

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.

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

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.
-
 ----------
 
 """

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