Merge remote-tracking branch 'upstream/main' into D401_imperative_mood

* upstream/main:
  ruff compliance for D205. (SciTools#5681)
  Added whatsnew to warnings PR (SciTools#5696)
  Removed use of catch_warnings (SciTools#5685)
  Better documentation for Cube names in curl (SciTools#5680)
  fix typo (SciTools#5689)
  Make further topics obviously different (SciTools#5684)
  [pre-commit.ci] pre-commit autoupdate (SciTools#5682)

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     -   id: no-commit-to-branch
 
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.9"
+    rev: "v0.1.11"
     hooks:
     -   id: ruff
         types: [file, python]
@@ -45,7 +45,7 @@ repos:
         additional_dependencies: [tomli]
 
 -   repo: https://github.com/PyCQA/flake8
-    rev: 6.1.0
+    rev: 7.0.0
     hooks:
     -   id: flake8
         types: [file, python]

benchmarks/asv_delegated_conda.py

@@ -4,8 +4,7 @@
 # See LICENSE in the root of the repository for full licensing details.
 """ASV plug-in providing an alternative :class:`asv.plugins.conda.Conda` subclass.
 
-ASV plug-in providing an alternative :class:`asv.plugins.conda.Conda`
-subclass that manages the Conda environment via custom user scripts.
+Manages the Conda environment via custom user scripts.
 
 """
 

benchmarks/benchmarks/cperf/load.py

@@ -10,7 +10,7 @@
 @on_demand_benchmark
 class SingleDiagnosticLoad(SingleDiagnosticMixin):
     def time_load(self, _, __, ___):
-        """Time load, the 'real world comparison'.
+        """Perform a 'real world comparison'.
 
         * UM coords are always realised (DimCoords).
         * LFRic coords are not realised by default (MeshCoords).

benchmarks/benchmarks/sperf/equality.py

@@ -12,7 +12,7 @@ class CubeEquality(FileMixin):
     r"""Benchmark time and memory costs.
 
     Benchmark time and memory costs of comparing :class:`~iris.cube.Cube`\\ s
-     with attached :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es.
+    with attached :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es.
 
     Uses :class:`FileMixin` as the realistic case will be comparing
     :class:`~iris.cube.Cube`\\ s that have been loaded from file.

docs/src/conf.py

@@ -291,7 +291,6 @@ def _dotv(version):
 html_theme_options = {
     "footer_start": ["copyright", "sphinx-version"],
     "footer_end": ["custom_footer"],
-    "collapse_navigation": True,
     "navigation_depth": 3,
     "show_prev_next": True,
     "navbar_align": "content",

docs/src/whatsnew/latest.rst

@@ -24,7 +24,7 @@ This document explains the changes made to Iris for this release
 📢 Announcements
 ================
 
-#. `@lbdreyer`_ relicensed Iris from LGPL-3 to BSD-3. (:pull: `5577`)
+#. `@lbdreyer`_ relicensed Iris from LGPL-3 to BSD-3. (:pull:`5577`)
 
 #. `@HGWright`_, `@bjlittle`_ and `@trexfeathers`_ (reviewers) added a
    CITATION.cff file to Iris and updated the :ref:`citation documentation <Citing_Iris>`
@@ -83,6 +83,10 @@ This document explains the changes made to Iris for this release
 #. `@rcomer`_ and `@trexfeathers`_ (reviewer) added handling for realization
    coordinates when saving pp files (:issue:`4747`, :pull:`5568`)
 
+#. `@ESadek-MO`_ has updated
+   :mod:`iris.fileformats._nc_load_rules.helpers` to lessen warning duplication.
+   (:issue:`5536`, :pull:`5685`)
+
 
 💣 Incompatible Changes
 =======================
@@ -142,6 +146,17 @@ This document explains the changes made to Iris for this release
 
 #. `@bouweandela`_ updated all hyperlinks to https. (:pull:`5621`)
 
+#. `@ESadek-MO`_ created an index page for :ref:`further_topics_index`, and
+   relocated all 'Technical Papers' into
+   :ref:`further_topics_index`. (:pull:`5602`)
+
+#. `@trexfeathers`_ made drop-down icons visible to show which pages link to
+   'sub-pages'. (:pull:`5684`)
+
+#. `@trexfeathers`_ improved the documentation of acceptable
+   :class:`~iris.cube.Cube` standard names in
+   :func:`iris.analysis.calculus.curl`. (:pull:`5680`)
+
 
 💼 Internal
 ===========

lib/iris/_concatenate.py

@@ -387,9 +387,6 @@ class _CubeSignature:
     def __init__(self, cube):
         """Represent the cube metadata and associated coordinate metadata.
 
-        Represents the cube metadata and associated coordinate metadata that
-        allows suitable cubes for concatenation to be identified.
-
         Parameters
         ----------
         cube : :class:`iris.cube.Cube`
@@ -733,10 +730,7 @@ class _ProtoCube:
     """Framework for concatenating multiple source-cubes over one common dimension."""
 
     def __init__(self, cube):
-        """Create a new _ProtoCube  and record the cube as a source-cube.
-
-        Create a new _ProtoCube from the given cube and record the cube
-        as a source-cube.
+        """Create a new _ProtoCube from the given cube and record the cube as a source-cube.
 
         Parameters
         ----------

lib/iris/_data_manager.py

@@ -285,7 +285,7 @@ def copy(self, data=None):
         return self._deepcopy(memo, data=data)
 
     def core_data(self):
-        """If real data is being managed, return the numpy.ndarray or numpy.ma.core.MaskedArray.
+        """Provide real data or lazy data.
 
         If real data is being managed, then return the :class:`~numpy.ndarray`
         or :class:`numpy.ma.core.MaskedArray`. Otherwise, return the lazy

lib/iris/_lazy_data.py

@@ -42,7 +42,7 @@ def is_lazy_data(data):
 
 
 def is_lazy_masked_data(data):
-    """Is it 'lazy' data array and the underlying array is of masked type.
+    """Determine whether managed data is lazy and masked.
 
     Return True if the argument is both an Iris 'lazy' data array and the
     underlying array is of masked type.  Otherwise return False.

lib/iris/_merge.py

@@ -859,6 +859,10 @@ def _build_separable_group(
 ):
     """Update the space with the first separable consistent group.
 
+    Update the space with the first separable consistent group that
+    satisfies a valid functional relationship with all other candidate
+    dimensions in the group.
+
     For example, the group ABCD and separable consistent group CD,
     if A = f(C, D) and B = f(C, D) then update the space with
     "A: (C, D), B: (C, D), C: None, D: None". Where "A: (C, D)" means
@@ -1518,7 +1522,7 @@ def name_in_independents():
         self._shape.extend(signature.data_shape)
 
     def _get_cube(self, data):
-        """Return fully constructed, containing all its coordinates and metadata.
+        """Generate fully constructed cube.
 
         Return a fully constructed cube for the given data, containing
         all its coordinates and metadata.

lib/iris/_representation/cube_printout.py

@@ -9,7 +9,7 @@
 
 
 class Table:
-    """A container of text strings in rows + columns.
+    """A container of text strings in rows and columns.
 
     A container of text strings in rows + columns, that can format its content
     into a string per row, with contents in columns of fixed width.
@@ -118,7 +118,7 @@ def __str__(self):
 
 
 class CubePrinter:
-    """An object created from a :class:`iris._representation.CubeSummary`.
+    """An object created from a cube summary.
 
     An object created from a
     :class:`iris._representation.CubeSummary`, which provides

lib/iris/analysis/_interpolation.py

@@ -57,7 +57,7 @@ def convert_date(date):
 
 
 def extend_circular_coord(coord, points):
-    """Return coordinates points with a shape extended by one.
+    """Return coordinate points with a shape extended by one.
 
     This is common when dealing with circular coordinates.
 
@@ -68,7 +68,7 @@ def extend_circular_coord(coord, points):
 
 
 def extend_circular_coord_and_data(coord, data, coord_dim):
-    """Return coordinate points and data array with a shape extended by one in the coord_dim axis.
+    """Return coordinate points and data with a shape extended by one in the provided axis.
 
     Return coordinate points and a data array with a shape extended by one
     in the coord_dim axis. This is common when dealing with circular
@@ -467,7 +467,7 @@ def _interpolated_dtype(self, dtype):
         return result
 
     def _points(self, sample_points, data, data_dims=None):
-        """Interpolate values at the specified list of orthogonal (coord, points) pairs.
+        """Interpolate at the specified points.
 
         Interpolate the given data values at the specified list of orthogonal
         (coord, points) pairs.

lib/iris/analysis/_regrid.py

@@ -431,7 +431,7 @@ def _get_horizontal_coord(cube, axis):
         return coords[0]
 
     def __call__(self, src):
-        """Regrid :class:`~iris.cube.Cube` onto the target grid :class:`_CurvilinearRegridder`.
+        """Regrid onto the target grid.
 
         Regrid the supplied :class:`~iris.cube.Cube` on to the target grid of
         this :class:`_CurvilinearRegridder`.
@@ -555,7 +555,7 @@ def extrapolation_mode(self):
 
     @staticmethod
     def _sample_grid(src_coord_system, grid_x_coord, grid_y_coord):
-        """Convert the rectilinear grid coordinates to a curvilinear grid.
+        """Convert the rectilinear grid to a curvilinear grid.
 
         Convert the rectilinear grid coordinates to a curvilinear grid in
         the source coordinate system.
@@ -852,7 +852,7 @@ def _check_units(self, coord):
                 raise ValueError(msg)
 
     def __call__(self, src):
-        """Regrid :class:`~iris.cube.Cube` onto target grid of :class:`RectilinearRegridder`.
+        """Regrid onto target grid.
 
         Regrid this :class:`~iris.cube.Cube` on to the target grid of
         this :class:`RectilinearRegridder`.

lib/iris/analysis/calculus.py

@@ -25,7 +25,7 @@
 from iris.exceptions import IrisUserWarning
 from iris.util import delta
 
-__all__ = ["cube_delta", "curl", "differentiate"]
+__all__ = ["DIRECTIONAL_NAMES", "cube_delta", "curl", "differentiate"]
 
 
 def _construct_delta_coord(coord):
@@ -471,6 +471,9 @@ def curl(i_cube, j_cube, k_cube=None):
     Calculate the 2-dimensional or 3-dimensional spherical or cartesian
     curl of the given vector of cubes.
 
+    The cube standard names must match one of the combinations in
+    :data:`DIRECTIONAL_NAMES`.
+
     As well as the standard x and y coordinates, this function requires each
     cube to possess a vertical or z-like coordinate (representing some form
     of height or pressure).  This can be a scalar or dimension coordinate.
@@ -734,12 +737,27 @@ def curl(i_cube, j_cube, k_cube=None):
     return result
 
 
+#: Acceptable X-Y-Z standard name combinations that
+#:  :func:`curl` can use (via :func:`spatial_vectors_with_phenom_name`).
+DIRECTIONAL_NAMES: tuple[tuple[str, str, str], ...] = (
+    ("u", "v", "w"),
+    ("x", "y", "z"),
+    ("i", "j", "k"),
+    ("eastward", "northward", "upward"),
+    ("easterly", "northerly", "vertical"),
+    ("easterly", "northerly", "radial"),
+)
+
+
 def spatial_vectors_with_phenom_name(i_cube, j_cube, k_cube=None):
     """Given spatially dependent cubes, return a list of the spatial coordinate names.
 
     Given 2 or 3 spatially dependent cubes, return a list of the spatial
     coordinate names with appropriate phenomenon name.
 
+    The cube standard names must match one of the combinations in
+    :data:`DIRECTIONAL_NAMES`.
+
     This routine is designed to identify the vector quantites which each
     of the cubes provided represent and return a list of their 3d
     spatial dimension names and associated phenomenon.
@@ -757,15 +775,6 @@ def spatial_vectors_with_phenom_name(i_cube, j_cube, k_cube=None):
 
 
     """
-    directional_names = (
-        ("u", "v", "w"),
-        ("x", "y", "z"),
-        ("i", "j", "k"),
-        ("eastward", "northward", "upward"),
-        ("easterly", "northerly", "vertical"),
-        ("easterly", "northerly", "radial"),
-    )
-
     # Create a list of the standard_names of our incoming cubes
     # (excluding the k_cube if it is None).
     cube_standard_names = [
@@ -795,7 +804,7 @@ def spatial_vectors_with_phenom_name(i_cube, j_cube, k_cube=None):
     # Get the appropriate direction list from the cube_directions we
     # have got from the standard name.
     direction = None
-    for possible_direction in directional_names:
+    for possible_direction in DIRECTIONAL_NAMES:
         # If this possible direction (minus the k_cube if it is none)
         # matches direction from the given cubes use it.
         if possible_direction[0 : len(cube_directions)] == cube_directions:
@@ -804,7 +813,7 @@ def spatial_vectors_with_phenom_name(i_cube, j_cube, k_cube=None):
     # If we didn't get a match, raise an Exception
     if direction is None:
         direction_string = "; ".join(
-            ", ".join(possible_direction) for possible_direction in directional_names
+            ", ".join(possible_direction) for possible_direction in DIRECTIONAL_NAMES
         )
         raise ValueError(
             "{} are not recognised vector cube_directions. "

lib/iris/analysis/cartography.py

@@ -83,7 +83,7 @@ def wrap_lons(lons, base, period):
 
 
 def unrotate_pole(rotated_lons, rotated_lats, pole_lon, pole_lat):
-    """Convert arrays of rotated-pole to unrotated arrays of longitudes and latitudes.
+    """Convert rotated-pole to unrotated longitudes and latitudes.
 
     ``pole_lat`` should describe the location of the rotated pole that
     describes the arrays of rotated-pole longitudes and latitudes.
@@ -133,7 +133,7 @@ def unrotate_pole(rotated_lons, rotated_lats, pole_lon, pole_lat):
 
 
 def rotate_pole(lons, lats, pole_lon, pole_lat):
-    """Convert arrays of longitudes and latitudes to arrays of rotated-pole longitudes and latitudes.
+    """Convert unrotated longitudes and latitudes to rotated-pole.
 
     The values of ``pole_lon`` and ``pole_lat``
     should describe the rotated pole that the arrays of longitudes and
@@ -496,7 +496,7 @@ def area_weights(cube, normalize=False):
 
 
 def cosine_latitude_weights(cube):
-    r"""Return an array of latitude weights, with the same dimensions as the cube.
+    r"""Calculate cosine latitude weights, with the same dimensions as the cube.
 
     Return an array of latitude weights, with the same dimensions as
     the cube. The weights are the cosine of latitude.
@@ -996,7 +996,7 @@ def _crs_distance_differentials(crs, x, y):
 
 
 def _transform_distance_vectors(u_dist, v_dist, ds, dx2, dy2):
-    """Transform distance vectors from one coordinate reference system to another.
+    """Transform distance vectors to another coordinate reference system.
 
     Transform distance vectors from one coordinate reference system to
     another, preserving magnitude and physical direction.

lib/iris/analysis/geometry.py

@@ -18,7 +18,7 @@
 
 
 def _extract_relevant_cube_slice(cube, geometry):
-    """Given a shapely geometry object.
+    """Calculate geometry intersection with spatial region defined by cube.
 
     This helper method returns the tuple
     (subcube, x_coord_of_subcube, y_coord_of_subcube,

lib/iris/analysis/maths.py

@@ -971,7 +971,7 @@ def _broadcast_cube_coord_data(cube, other, operation_name, dim=None):
 
 
 def _sanitise_metadata(cube, unit):
-    """Clear the necessary or unsupported metadata from the resultant cube.
+    """Clear appropriate metadata from the resultant cube.
 
     As part of the maths metadata contract, clear the necessary or
     unsupported metadata from the resultant cube of the maths operation.

lib/iris/analysis/trajectory.py

@@ -530,7 +530,7 @@ def _cartesian_sample_points(sample_points, sample_point_coord_names):
 
 
 def _nearest_neighbour_indices_ndcoords(cube, sample_points, cache=None):
-    """Return indices to select data value(s) closest to the given coordinate point values.
+    """Calculate the cube nearest neighbour indices for the samples.
 
     Return the indices to select the data value(s) closest to the given
     coordinate point values.