ruff rule D412 compliance. (#5660)

* ruff rule D412 complliance.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update _optimal_array_structuring.py

remove trailing whitespace.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.ruff.toml

@@ -48,7 +48,6 @@ lint.ignore = [
     "D407",  # Missing dashed underline after section
     "D409",  # Section underline should match the length of its name
     "D410",  # Missing blank line after section
-    "D412",  # No blank lines allowed between a section header and its content 
 
     # pyupgrade (UP)
     # https://docs.astral.sh/ruff/rules/#pyupgrade-up

docs/gallery_code/general/plot_SOI_filtering.py

@@ -11,7 +11,6 @@
 
 References
 ----------
-
     Duchon C. E. (1979) Lanczos Filtering in One and Two Dimensions.
     Journal of Applied Meteorology, Vol 18, pp 1016-1022.
 

docs/gallery_code/meteorology/plot_COP_1d.py

@@ -11,7 +11,6 @@
 
 References
 ----------
-
    Johns T.C., et al. (2011) Climate change under aggressive mitigation: the
    ENSEMBLES multi-model experiment. Climate Dynamics, Vol 37, No. 9-10,
    doi:10.1007/s00382-011-1005-5.

docs/gallery_code/meteorology/plot_COP_maps.py

@@ -9,7 +9,6 @@
 
 References
 ----------
-
     Johns T.C., et al. (2011) Climate change under aggressive mitigation: the
     ENSEMBLES multi-model experiment. Climate Dynamics, Vol 37, No. 9-10,
     doi:10.1007/s00382-011-1005-5.

lib/iris/analysis/_grid_angles.py

@@ -22,9 +22,9 @@ def _3d_xyz_from_latlon(lon, lat):
         Arrays of longitudes and latitudes, in degrees.
         Both the same shape.
 
-    Returns:
-
-    * xyz : (array, dtype=float64)
+    Returns
+    -------
+    xyz : array, dtype=float64
         Cartesian coordinates on a unit sphere.
         Shape is (3, <input-shape>).
         The x / y / z coordinates are in xyz[0 / 1 / 2].
@@ -52,9 +52,9 @@ def _latlon_from_xyz(xyz):
         Shape (3, <input_points_dimensions>).
         x / y / z values are in xyz[0 / 1 / 2],
 
-    Returns:
-
-    * lonlat : (array)
+    Returns
+    -------
+    lonlat : array
         longitude and latitude position angles, in degrees.
         Shape (2, <input_points_dimensions>).
         The longitudes / latitudes are in lonlat[0 / 1].
@@ -104,9 +104,9 @@ def _angle(p, q, r):
         Shape is (2, <input_points_dimensions>).
         Longitudes / latitudes are in array[0 / 1].
 
-    Returns:
-
-    * angle : (float array)
+    Returns
+    -------
+    angle : float array
         Grid angles relative to true-East, in degrees.
         Positive when grid-East is anticlockwise from true-East.
         Shape is same as <input_points_dimensions>.
@@ -178,23 +178,22 @@ def gridcell_angles(x, y=None, cell_angle_boundpoints="mid-lhs, mid-rhs"):
         takes an angles between the average of the left-hand and right-hand
         pairs of corners.  The default is 'mid-lhs, mid-rhs'.
 
-    Returns:
-
-        angles : (2-dimensional cube)
-
-            Cube of angles of grid-x vector from true Eastward direction for
-            each gridcell, in degrees.
-            It also has "true" longitude and latitude coordinates, with no
-            coordinate system.
-            When the input has coords, then the output ones are identical if
-            the inputs are true-latlons, otherwise they are transformed
-            true-latlon versions.
-            When the input has bounded coords, then the output coords have
-            matching bounds and centrepoints (possibly transformed).
-            When the input is 2d arrays, or has unbounded coords, then the
-            output coords have matching points and no bounds.
-            When the input is 3d arrays, then the output coords have matching
-            bounds, and the centrepoints are an average of the 4 boundpoints.
+    Returns
+    -------
+    angles : 2-dimensional cube
+        Cube of angles of grid-x vector from true Eastward direction for
+        each gridcell, in degrees.
+        It also has "true" longitude and latitude coordinates, with no
+        coordinate system.
+        When the input has coords, then the output ones are identical if
+        the inputs are true-latlons, otherwise they are transformed
+        true-latlon versions.
+        When the input has bounded coords, then the output coords have
+        matching bounds and centrepoints (possibly transformed).
+        When the input is 2d arrays, or has unbounded coords, then the
+        output coords have matching points and no bounds.
+        When the input is 3d arrays, then the output coords have matching
+        bounds, and the centrepoints are an average of the 4 boundpoints.
 
     """
     cube = None
@@ -423,15 +422,17 @@ def rotate_grid_vectors(u_cube, v_cube, grid_angles_cube=None, grid_angles_kwarg
         Additional keyword args to be passed to the :func:`gridcell_angles`
         method, if it is used.
 
-    Returns:
-
-        true_u, true_v : (cube)
-            Cubes of true-north oriented vector components.
-            Units are same as inputs.
+    Returns
+    -------
+    true_u, true_v : cube
+        Cubes of true-north oriented vector components.
+        Units are same as inputs.
 
-        .. Note::
+    Notes
+    -----
+    .. note::
 
-            Vector magnitudes will always be the same as the inputs.
+        Vector magnitudes will always be the same as the inputs.
 
     .. note::
 

lib/iris/analysis/_interpolation.py

@@ -296,9 +296,10 @@ def _interpolate(self, data, interp_points):
             The other (leading) dimensions index over the different required
             sample points.
 
-        Returns:
-
-            A :class:`np.ndarray`.  Its shape is "points_shape + extra_shape",
+        Returns
+        -------
+        :class:`np.ndarray`.
+            Its shape is "points_shape + extra_shape",
             where "extra_shape" is the remaining non-interpolated dimensions of
             the data array (i.e. 'data.shape[N:]'), and "points_shape" is the
             leading dimensions of interp_points,

lib/iris/analysis/cartography.py

@@ -482,8 +482,8 @@ def cosine_latitude_weights(cube):
 
            w_l = \cos \phi_l
 
-    Examples:
-
+    Examples
+    --------
     Compute weights suitable for averaging type operations::
 
         from iris.analysis.cartography import cosine_latitude_weights

lib/iris/analysis/maths.py

@@ -218,7 +218,6 @@ def add(cube, other, dim=None, in_place=False):
 
     Parameters
     ----------
-
     cube : iris.cube.Cube
         First operand to add.
 
@@ -234,7 +233,6 @@ def add(cube, other, dim=None, in_place=False):
 
     Returns
     -------
-
     iris.cube.Cube
 
     Notes
@@ -273,7 +271,6 @@ def subtract(cube, other, dim=None, in_place=False):
 
     Parameters
     ----------
-
     cube : iris.cube.Cube
         Cube from which to subtract.
 
@@ -289,7 +286,6 @@ def subtract(cube, other, dim=None, in_place=False):
 
     Returns
     -------
-
     iris.cube.Cube
 
     Notes
@@ -378,7 +374,6 @@ def multiply(cube, other, dim=None, in_place=False):
 
     Parameters
     ----------
-
     cube : iris.cube.Cube
         First operand to multiply.
 
@@ -394,7 +389,6 @@ def multiply(cube, other, dim=None, in_place=False):
 
     Returns
     -------
-
     iris.cube.Cube
 
     Notes
@@ -464,7 +458,6 @@ def divide(cube, other, dim=None, in_place=False):
 
     Parameters
     ----------
-
     cube : iris.cube.Cube
         Numerator.
 
@@ -480,7 +473,6 @@ def divide(cube, other, dim=None, in_place=False):
 
     Returns
     -------
-
     iris.cube.Cube
 
     Notes

lib/iris/coord_systems.py

@@ -999,7 +999,6 @@ def __init__(
 
         Parameters
         ----------
-
         central_lat : float
             The latitude of the pole.
 
@@ -1113,7 +1112,6 @@ def __init__(
 
         Parameters
         ----------
-
         central_lat : {90, -90}
             The latitude of the pole.
 

lib/iris/cube.py

@@ -772,7 +772,6 @@ class CubeAttrsDict(MutableMapping):
 
     Examples
     --------
-
         >>> from iris.cube import Cube
         >>> cube = Cube([0])
         >>> # CF defines 'history' as global by default.
@@ -829,7 +828,6 @@ def __init__(
 
         Examples
         --------
-
             >>> from iris.cube import CubeAttrsDict
             >>> # CF defines 'history' as global by default.
             >>> CubeAttrsDict({'history': 'data-story', 'comment': 'this-cube'})
@@ -2364,11 +2362,11 @@ def mesh(self):
         :class:`~iris.experimental.ugrid.MeshCoord`\\ s,
         or ``None`` if it has none.
 
-        Returns:
-
-        * mesh (:class:`iris.experimental.ugrid.mesh.Mesh` or None):
+        Returns
+        -------
+        mesh : :class:`iris.experimental.ugrid.mesh.Mesh` or None
             The mesh of the cube
-            :class:`~iris.experimental.ugrid.MeshCoord`\\s,
+            :class:`~iris.experimental.ugrid.MeshCoord`'s,
             or ``None``.
 
         """
@@ -2383,13 +2381,12 @@ def location(self):
         :class:`~iris.experimental.ugrid.MeshCoord`\\ s,
         or ``None`` if it has none.
 
-        Returns:
-
-        * location (str or None):
+        Returns
+        -------
+        location : str or None
             The mesh location of the cube
-            :class:`~iris.experimental.ugrid.MeshCoord`\\s
-            (i.e. one of 'face' / 'edge' / 'node'),
-            or ``None``.
+            :class:`~iris.experimental.ugrid.MeshCoord`'s
+            (i.e. one of 'face' / 'edge' / 'node'), or ``None``.
 
         """
         result = self._any_meshcoord()
@@ -2402,10 +2399,10 @@ def mesh_dim(self):
         :class:`~iris.experimental.ugrid.MeshCoord`\\ s,
         or ``None`` if it has none.
 
-        Returns:
-
-        * mesh_dim (int, or None):
-            the cube dimension which the cube
+        Returns
+        -------
+        mesh_dim : int or None
+            The cube dimension which the cube
             :class:`~iris.experimental.ugrid.MeshCoord`\\s map to,
             or ``None``.
 
@@ -4191,7 +4188,6 @@ def aggregated_by(self, coords, aggregator, climatological=False, **kwargs):
 
         Examples
         --------
-
             >>> import iris
             >>> import iris.analysis
             >>> import iris.coord_categorisation as cat

lib/iris/fileformats/_nc_load_rules/helpers.py

@@ -266,10 +266,10 @@ def _split_cell_methods(nc_cell_methods: str) -> List[re.Match]:
 
     * nc_cell_methods: The value of the cell methods attribute to be split.
 
-    Returns:
-
-    * nc_cell_methods_matches: A list of the re.Match objects associated with
-      each parsed cell method
+    Returns
+    -------
+    nc_cell_methods_matches: list of re.Match objects
+        A list of re.Match objects associated with each parsed cell method
 
     Splitting is done based on words followed by colons outside of any brackets.
     Validation of anything other than being laid out in the expected format is
@@ -337,10 +337,9 @@ def parse_cell_methods(nc_cell_methods):
     * nc_cell_methods (str):
         The value of the cell methods attribute to be parsed.
 
-    Returns:
-
-    * cell_methods
-        An iterable of :class:`iris.coords.CellMethod`.
+    Returns
+    -------
+    iterable of :class:`iris.coords.CellMethod`.
 
     Multiple coordinates, intervals and comments are supported.
     If a method has a non-standard name a warning will be issued, but the

lib/iris/fileformats/cf.py

@@ -6,9 +6,8 @@
 according to the 'NetCDF Climate and Forecast (CF) Metadata Conventions'.
 
 References:
-
-[CF]  NetCDF Climate and Forecast (CF) Metadata conventions.
-[NUG] NetCDF User's Guide, https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/
+    [CF]  NetCDF Climate and Forecast (CF) Metadata conventions.
+    [NUG] NetCDF User's Guide, https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/
 
 """
 

lib/iris/fileformats/pp_load_rules.py

@@ -317,9 +317,9 @@ def _reshape_vector_args(values_and_dims):
         Input arrays with associated mapping dimension numbers.
         The length of each 'dims' must match the ndims of the 'value'.
 
-    Returns:
-
-    * reshaped_arrays (iterable of arrays).
+    Returns
+    -------
+    reshaped_arrays : iterable of arrays
         The inputs, transposed and reshaped onto common target dimensions.
 
     """
@@ -371,9 +371,9 @@ def _collapse_degenerate_points_and_bounds(points, bounds=None, rtol=1.0e-7):
         dimension (typically of length 2) when compared to the  points array
         i.e. bounds.shape = points.shape + (nvertex,)
 
-    Returns:
-
-        A (points, bounds) tuple.
+    Returns
+    -------
+    (points, bounds) tuple.
 
     """
     array = points
@@ -634,9 +634,10 @@ def _convert_time_coords(
         to (). The length of each dims tuple should equal the dimensionality
         of the corresponding array of values.
 
-    Returns:
-
-        A list of (coordinate, dims) tuples. The coordinates are instance of
+    Returns
+    -------
+    list of (coordinate, dims) tuples.
+        The coordinates are instance of
         :class:`iris.coords.DimCoord` if possible, otherwise they are instance
         of :class:`iris.coords.AuxCoord`. When the coordinate is of length one,
         the `dims` value is None rather than an empty tuple.