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

* upstream/main: Bump codecov/codecov-action from 3 to 4 (SciTools#5727) DOCS: API docs ToC more levels (SciTools#5714) Bump scitools/workflows from 2024.01.0 to 2024.02.0 (SciTools#5726) DOCS: numpydocs 8 (SciTools#5722) DOCS: numpydocs 7 (SciTools#5720) DOCS: numpydocs 6 (SciTools#5718) fix docstring types and remove duplicate line. (SciTools#5719)
tkknight · Feb 5, 2024 · 2b979f2 · 2b979f2
2 parents 48c03ad + b864a82
commit 2b979f2
Show file tree

Hide file tree

Showing 42 changed files with 756 additions and 830 deletions.
diff --git a/.github/workflows/ci-manifest.yml b/.github/workflows/ci-manifest.yml
@@ -23,4 +23,4 @@ concurrency:
 jobs:
   manifest:
     name: "check-manifest"
-    uses: scitools/workflows/.github/workflows/ci-manifest.yml@2024.01.0
+    uses: scitools/workflows/.github/workflows/ci-manifest.yml@2024.02.0
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
@@ -140,5 +140,5 @@ jobs:
           nox --session ${{ matrix.session }} -- --verbose ${{ matrix.coverage }}
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         if: ${{ matrix.coverage }}
diff --git a/.github/workflows/refresh-lockfiles.yml b/.github/workflows/refresh-lockfiles.yml
@@ -14,5 +14,5 @@ on:
 
 jobs:
   refresh_lockfiles:
-    uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2024.01.0
+    uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2024.02.0
     secrets: inherit
diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -195,9 +195,17 @@ def _dotv(version):
 # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
 todo_include_todos = True
 
-# api generation configuration
-autodoc_member_order = "alphabetical"
-autodoc_default_flags = ["show-inheritance"]
+# sphinx.ext.autodoc configuration --------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options
+autodoc_default_options = {
+    "members": True,
+    "member-order": "alphabetical",
+    "undoc-members": True,
+    "private-members": False,
+    "special-members": False,
+    "inherited-members": True,
+    "show-inheritance": True,
+}
 
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints
 autodoc_typehints = "none"
@@ -292,6 +300,7 @@ def _dotv(version):
     "footer_start": ["copyright", "sphinx-version"],
     "footer_end": ["custom_footer"],
     "navigation_depth": 3,
+    "show_toc_level": 2,
     "show_prev_next": True,
     "navbar_align": "content",
     # removes the search box from the top bar
@@ -319,7 +328,6 @@ def _dotv(version):
         },
     ],
     "use_edit_page_button": True,
-    "show_toc_level": 1,
     # Omit `theme-switcher` from navbar_end below to disable it
     # Info: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/light-dark.html#configure-default-theme-mode
     # "navbar_end": ["navbar-icon-links"],

diff --git a/docs/src/further_topics/filtering_warnings.rst b/docs/src/further_topics/filtering_warnings.rst
@@ -49,7 +49,7 @@ Warnings:
     ...
     iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
-    iris/coord_systems.py:782: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 Warnings can be suppressed using the Python warnings filter with the ``ignore``
@@ -130,7 +130,7 @@ Or you can target Warnings raised by specific lines of specific modules, e.g.
     ...
     iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
       warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
-    iris/coord_systems.py:782: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 ::

diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
@@ -172,6 +172,9 @@ This document explains the changes made to Iris for this release
 #. `@tkknight`_ added ruff documentation in the :ref:`developer_testing_ci` of the
    :ref:`developers_guide`. (:pull:`5701`)
 
+#. `@tkknight`_ configured the API documentation to show 2 levels
+   for the ToC (Table of Contents) for each page. (:pull:`5714`)
+
 
 💼 Internal
 ===========

diff --git a/lib/iris/_lazy_data.py b/lib/iris/_lazy_data.py
@@ -252,7 +252,7 @@ def as_lazy_data(
     Notes
     -----
     The result chunk size is a multiple of 'chunks', if given, up to the
-    dask default chunksize, i.e. `dask.config.get('array.chunk-size'),
+    dask default chunksize, i.e. `dask.config.get('array.chunk-size')`,
     or the full data shape if that is smaller.
     If 'chunks' is not given, the result has chunks of the full data shape,
     but reduced by a factor if that exceeds the dask default chunksize.

diff --git a/lib/iris/_merge.py b/lib/iris/_merge.py
@@ -5,7 +5,7 @@
 """Automatic collation of cubes into higher-dimensional cubes.
 
 Typically the cube merge process is handled by
-:method:`iris.cube.CubeList.merge`.
+:meth:`iris.cube.CubeList.merge`.
 
 """
 

diff --git a/lib/iris/_representation/cube_printout.py b/lib/iris/_representation/cube_printout.py
@@ -58,7 +58,7 @@ def add_row(self, cols, aligns, i_col_unlimited=None):
             Per-column content.  Length must match the other rows (if any).
         aligns : list of {'left', 'right'}
             Per-column alignments.  Length must match 'cols'.
-        i_col_unlimited : int or None, optional
+        i_col_unlimited : int, optional
             Column beyond which content does not affect the column widths.
             ( meaning contents will print without limit ).
 
@@ -325,10 +325,10 @@ def to_string(self, oneline=False, name_padding=35):
 
         Parameters
         ----------
-        oneline : bool, optional, default=False
+        oneline : bool, default=False
             If set, produce a one-line summary.
             Default is False = produce full (multiline) summary.
-        name_padding int, optional, default=35
+        name_padding : int, default=35
             The minimum width for the "name" (#0) column.
 
         Returns

diff --git a/lib/iris/common/lenient.py b/lib/iris/common/lenient.py
@@ -60,7 +60,7 @@ def func():
         wrapped by the decorator. This is automatically populated by Python
         through the decorator interface. No argument requires to be manually
         provided.
-    services : callable or str or iterable of callable/str, optional, default=None
+    services : callable or str or iterable of callable/str, optional
         Zero or more function/methods, or equivalent fully qualified string names, of
         lenient service function/methods.
 
@@ -227,7 +227,7 @@ def __init__(self, **kwargs):
 
         Parameters
         ----------
-        **kwargs : dict
+        **kwargs : dict, optional
             Mapping of lenient key/value options to enable/disable. Note that,
             only the lenient "maths" options is available, which controls
             lenient/strict cube arithmetic.
@@ -298,7 +298,6 @@ def context(self, **kwargs):
         applied. On exit from the context manager, the previous lenient
         option state is restored.
 
-
         For example::
 
             with iris.common.Lenient.context(maths=False):
@@ -555,7 +554,7 @@ def register_client(self, func, services, append=False):
         services : callable or str or iterable of callable/str
             One or more service function/methods or fully qualified string names
             of the required service function/method.
-        append : bool, optional
+        append : bool, default=False
             If True, append the lenient services to any pre-registered lenient
             services for the provided lenient client. Default is False.
 

diff --git a/lib/iris/common/metadata.py b/lib/iris/common/metadata.py
@@ -583,7 +583,7 @@ def combine(self, other, lenient=None):
         ----------
         other : metadata
             A metadata instance of the same type.
-        lenient : bool
+        lenient : bool, optional
             Enable/disable lenient combination. The default is to automatically
             detect whether this lenient operation is enabled.
 
@@ -694,7 +694,7 @@ def name(self, default=None, token=False):
         default : optional
             The fall-back string representing the default name. Defaults to
             the string 'unknown'.
-        token : bool, optional
+        token : bool, default=False
             If True, ensures that the name returned satisfies the criteria for
             the characters required by a valid NetCDF name. If it is not
             possible to return a valid name, then a ValueError exception is
@@ -1574,7 +1574,7 @@ def metadata_manager_factory(cls, **kwargs):
     cls :
         A subclass of :class:`~iris.common.metadata.BaseMetadata`, defining
         the metadata to be managed.
-    **kwargs :
+    **kwargs : dict, optional
         Initial values for the manufactured metadata instance. Unspecified
         fields will default to a value of 'None'.
 

diff --git a/lib/iris/common/resolve.py b/lib/iris/common/resolve.py
@@ -245,9 +245,9 @@ def __init__(self, lhs=None, rhs=None):
 
         Parameters
         ----------
-        lhs : :class:`~iris.cube.Cube`
+        lhs : :class:`~iris.cube.Cube`, optional
             The left-hand-side :class:`~iris.cube.Cube` operand.
-        rhs : :class:`~iris.cube.Cube`
+        rhs : :class:`~iris.cube.Cube`, optional
             The right-hand-side :class:`~iris.cube.Cube` operand.
 
         Examples
@@ -698,15 +698,15 @@ def _create_prepared_item(
             The dimensions that the ``coord`` spans on the resulting resolved
             :class:`~iris.cube.Cube`.
             (Can also be a single dimension number).
-        src_metadata :
+        src_metadata : optional
             The coordinate metadata from the ``src`` :class:`~iris.cube.Cube`.
-        tgt_metadata :
+        tgt_metadata : optional
             The coordinate metadata from the ``tgt`` :class:`~iris.cube.Cube`.
-        points :
+        points : optional
             Override points array.  When not given, use coord.points.
-        bounds :
+        bounds : optional
             Override bounds array.  When not given, use coord.bounds.
-        container :
+        container : optional
             Override coord type (class constructor).
             When not given, use type(coord).
 
@@ -1145,34 +1145,40 @@ def _metadata_coverage(self):
     def _metadata_mapping(self):
         """Identify equivalent dimensions using metadata.
 
-        Ensure that each ``src`` :class:`~iris.cube.Cube` dimension is mapped to an associated
-        ``tgt`` :class:`~iris.cube.Cube` dimension using the common dim and aux coordinate metadata.
+        Ensure that each ``src`` :class:`~iris.cube.Cube` dimension is mapped to an
+        associated ``tgt`` :class:`~iris.cube.Cube` dimension using the common dim
+        and aux coordinate metadata.
 
-        If the common metadata does not result in a full mapping of ``src`` to ``tgt`` dimensions
-        then free dimensions are analysed to determine whether the mapping can be completed.
+        If the common metadata does not result in a full mapping of ``src`` to ``tgt``
+        dimensions then free dimensions are analysed to determine whether the mapping
+        can be completed.
 
-        Once the ``src`` has been mapped to the ``tgt``, the cubes are checked to ensure that they
-        will successfully broadcast, and the ``src`` :class:`~iris.cube.Cube` is transposed appropriately,
-        if necessary.
+        Once the ``src`` has been mapped to the ``tgt``, the cubes are checked to
+        ensure that they will successfully broadcast, and the ``src``
+        :class:`~iris.cube.Cube` is transposed appropriately, if necessary.
 
-        The :attr:`~iris.common.resolve.Resolve._broadcast_shape` is set, along with the
-        :attr:`~iris.common.resolve.Resolve._src_cube_resolved` and :attr:`~iris.common.resolve.Resolve._tgt_cube_resolved`,
+        The :attr:`~iris.common.resolve.Resolve._broadcast_shape` is set, along with
+        the :attr:`~iris.common.resolve.Resolve._src_cube_resolved` and
+        :attr:`~iris.common.resolve.Resolve._tgt_cube_resolved`,
         which are the broadcast/transposed ``src`` and ``tgt``.
 
         .. note::
 
-            An exception will be raised if a ``src`` dimension cannot be mapped to a ``tgt`` dimension.
+            An exception will be raised if a ``src`` dimension cannot be mapped to
+            a ``tgt`` dimension.
 
         .. note::
 
-            An exception will be raised if the full mapped ``src`` :class:`~iris.cube.Cube` cannot be
-            broadcast or transposed with the ``tgt`` :class:`~iris.cube.Cube`.
+            An exception will be raised if the full mapped ``src``
+            :class:`~iris.cube.Cube` cannot be broadcast or transposed with the
+            ``tgt`` :class:`~iris.cube.Cube`.
 
         .. note::
 
-            The ``src`` and ``tgt`` may  be swapped in the case where they both have equal dimensionality and
-            the ``tgt`` does have the same shape as the resolved broadcast shape (and the ``src`` does) or
-            the ``tgt`` has more free dimensions than the ``src``.
+            The ``src`` and ``tgt`` may  be swapped in the case where they both have
+            equal dimensionality and the ``tgt`` does have the same shape as the
+            resolved broadcast shape (and the ``src`` does) or the ``tgt`` has more
+            free dimensions than the ``src``.
 
         """
         # Initialise the state.
@@ -1629,11 +1635,11 @@ def _get_prepared_item(
             The :class:`~iris.common.resolve._CategoryItems` containing the
             local metadata of either the ``src`` or ``tgt`` :class:`~iris.cube.Cube`.
             See ``from_local``.
-        from_src : bool, optional
+        from_src : bool, default=True
             Boolean stating whether the ``metadata`` is from the ``src`` (``True``)
             or ``tgt`` :class:`~iris.cube.Cube`.
             Defaults to ``True``.
-        from_local: bool, optional
+        from_local: bool, default=False
             Boolean controlling whether the ``metadata`` is used to search the
             ``category_local`` (``True``) or the :attr:`~iris.common.resolve.Resolve.prepared_category`.
             Defaults to ``False``.
@@ -1710,7 +1716,7 @@ def _prepare_factory_payload(self, cube, category_local, from_src=True):
         category_local : :class:`~iris.common.resolve._CategoryItems`
             The :class:`~iris.common.resolve._CategoryItems` of all metadata
             local to the provided ``cube``.
-        from_src : bool, optional, default=True
+        from_src : bool, default=True
             Boolean stating whether the provided ``cube`` is either a ``src`` or ``tgt``
             :class:`~iris.cube.Cube` - used to retrieve the appropriate metadata from a
             :class:`~iris.common.resolve._PreparedMetadata`.
@@ -2301,7 +2307,7 @@ def cube(self, data, in_place=False):
             The data payload for the resultant :class:`~iris.cube.Cube`, which
             **must match** the expected resolved
             :attr:`~iris.common.resolve.Resolve.shape`.
-        in_place : optional
+        in_place : bool, default=False
             If ``True``, the ``data`` is inserted into the ``tgt``
             :class:`~iris.cube.Cube`. The existing metadata of the ``tgt``
             :class:`~iris.cube.Cube` is replaced with the resolved metadata from

diff --git a/lib/iris/coord_categorisation.py b/lib/iris/coord_categorisation.py
@@ -40,7 +40,7 @@ def add_categorised_coord(cube, name, from_coord, category_function, units="1"):
     category_function : callable
         function(coordinate, value), returning a category value for a
         coordinate point-value
-    units : str, optional, default="1"
+    units : str, default="1"
         units of the category value, typically 'no_unit' or '1'.
     """
     # Interpret coord, if given as a name
@@ -303,7 +303,7 @@ def add_season(cube, coord, name="season", seasons=("djf", "mam", "jja", "son"))
         it.
     coord : :class:`iris.coords.Coord` or str
         Coordinate in 'cube', or its name, representing time.
-    name : str, optional
+    name : str, default="season"
         Name of the created coordinate. Defaults to "season".
     seasons : :class:`list` of str, optional
         List of seasons defined by month abbreviations. Each month must
@@ -341,7 +341,7 @@ def add_season_number(
         it.
     coord : :class:`iris.coords.Coord` or str
         Coordinate in 'cube', or its name, representing time.
-    name : str, optional
+    name : str, default="season"
         Name of the created coordinate. Defaults to "season_number".
     seasons : :class:`list` of str, optional
         List of seasons defined by month abbreviations. Each month must
@@ -425,7 +425,7 @@ def add_season_membership(cube, coord, season, name="season_membership"):
         Coordinate in 'cube', or its name, representing time.
     season : str
         Season defined by month abbreviations.
-    name : str, optional
+    name : str, default="season_membership"
         Name of the created coordinate. Defaults to "season_membership".
 
     """