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

* upstream/main:
  review actions
  update .git-blame-ignore-revs
  adopt codespell
  Adopt sphinx design (SciTools#5127)
  Bump scitools/workflows from 2023.04.2 to 2023.04.3 (SciTools#5253)

.git-blame-ignore-revs

@@ -1,2 +1,20 @@
 # Format: numpy array format (#5235)
 c18dcd8dafef0cc7bbbf80dfce66f76a46ce59c5
+
+# style: flake8 (#3755)
+7c86bc0168684345dc475457b1a77dadc77ce9bb
+
+# style: black (#3518)
+ffcfad475e0593e1e40895453cf1df154e5f6f2c
+
+# style: isort (#4174)
+15bbcc5ac3d539cb6e820148b66e7cf55d91c5d2
+
+# style: blacken-docs (#4205)
+1572e180243e492d8ff76fa8cdefb82ef6f90415
+
+# style: sort-all (#4353)
+64705dbc40881233aae45f051d96049150369e53
+
+# style: codespell (#5186)
+417aa6bbd9b10d25cad7def54d47ef4d718bc38d

.github/workflows/refresh-lockfiles.yml

@@ -14,5 +14,5 @@ on:
 
 jobs:
   refresh_lockfiles:
-    uses: scitools/workflows/.github/workflows/[email protected].2
+    uses: scitools/workflows/.github/workflows/[email protected].3
     secrets: inherit

.pre-commit-config.yaml

@@ -28,6 +28,13 @@ repos:
         # Don't commit to main branch.
     -   id: no-commit-to-branch
 
+-   repo: https://github.com/codespell-project/codespell
+    rev: "v2.2.2"
+    hooks:
+    -   id: codespell
+        types_or: [asciidoc, python, markdown, rst]
+        additional_dependencies: [tomli]
+
 -   repo: https://github.com/psf/black
     rev: 23.3.0
     hooks:

benchmarks/benchmarks/experimental/ugrid/regions_combine.py

@@ -50,7 +50,7 @@ def _make_region_cubes(self, full_mesh_cube):
         i_faces = np.concatenate([i_faces[:, 2:], i_faces[:, :2]], axis=1)
         # flatten to get [2 3 4 0 1 (-) 8 9 10 6 7 (-) 13 14 15 11 12 ...]
         i_faces = i_faces.flatten()
-        # reduce back to orignal length, wrap any overflows into valid range
+        # reduce back to original length, wrap any overflows into valid range
         i_faces = i_faces[:n_faces] % n_faces
 
         # Divide into regions -- always slightly uneven, since 7 doesn't divide

benchmarks/benchmarks/sperf/combine_regions.py

@@ -46,7 +46,7 @@ def _make_region_cubes(self, full_mesh_cube):
         i_faces = np.concatenate([i_faces[:, 2:], i_faces[:, :2]], axis=1)
         # flatten to get [2 3 4 0 1 (-) 8 9 10 6 7 (-) 13 14 15 11 12 ...]
         i_faces = i_faces.flatten()
-        # reduce back to orignal length, wrap any overflows into valid range
+        # reduce back to original length, wrap any overflows into valid range
         i_faces = i_faces[:n_faces] % n_faces
 
         # Divide into regions -- always slightly uneven, since 7 doesn't divide

codecov.yml

@@ -6,4 +6,4 @@ coverage:
         target: auto
         # coverage can drop by up to <threshold>% while still posting success
         threshold: 3%
-    patch: off
+    patch: off

docs/gallery_code/general/plot_projections_and_annotations.py

@@ -78,7 +78,7 @@ def make_plot(projection_name, projection_crs):
     y_points = y_lower + y_delta * np.concatenate(
         (zeros, steps, ones, steps[::-1])
     )
-    # Get the Iris coordinate sytem of the X coordinate (Y should be the same).
+    # Get the Iris coordinate system of the X coordinate (Y should be the same).
     cs_data1 = x_coord.coord_system
     # Construct an equivalent Cartopy coordinate reference system ("crs").
     crs_data1 = cs_data1.as_cartopy_crs()

docs/gallery_code/general/plot_rotated_pole_mapping.py

@@ -40,7 +40,7 @@ def main():
     plt.gca().coastlines()
     iplt.show()
 
-    # Plot #3: Contourf overlayed by coloured point data
+    # Plot #3: Contourf overlaid by coloured point data
     plt.figure()
     qplt.contourf(air_pressure)
     iplt.points(air_pressure, c=air_pressure.data)

docs/gallery_code/meteorology/plot_lagged_ensemble.py

@@ -5,16 +5,16 @@
 This example demonstrates the loading of a lagged ensemble dataset from the
 GloSea4 model, which is then used to produce two types of plot:
 
- * The first shows the "postage stamp" style image with an array of 14 images,
-   one for each ensemble member with a shared colorbar. (The missing image in
-   this example represents ensemble member number 6 which was a failed run)
+* The first shows the "postage stamp" style image with an array of 14 images,
+  one for each ensemble member with a shared colorbar. (The missing image in
+  this example represents ensemble member number 6 which was a failed run)
 
- * The second plot shows the data limited to a region of interest, in this case
-   a region defined for forecasting ENSO (El Nino-Southern Oscillation), which,
-   for the purposes of this example, has had the ensemble mean subtracted from
-   each ensemble member to give an anomaly surface temperature. In practice a
-   better approach would be to take the climatological mean, calibrated to the
-   model, from each ensemble member.
+* The second plot shows the data limited to a region of interest, in this case
+  a region defined for forecasting ENSO (El Nino-Southern Oscillation), which,
+  for the purposes of this example, has had the ensemble mean subtracted from
+  each ensemble member to give an anomaly surface temperature. In practice a
+  better approach would be to take the climatological mean, calibrated to the
+  model, from each ensemble member.
 
 """
 
@@ -115,7 +115,7 @@ def main():
     # Get the time for the entire plot.
     time = last_time_coord.units.num2date(last_time_coord.bounds[0, 0])
 
-    # Set a global title for the postage stamps with the date formated by
+    # Set a global title for the postage stamps with the date formatted by
     # "monthname year".
     time_string = time.strftime("%B %Y")
     plt.suptitle(f"Surface temperature ensemble forecasts for {time_string}")

docs/src/IEP/IEP001.adoc

@@ -119,7 +119,7 @@ cube.sel(height=1.5)
 
 The semantics of position-based slices will continue to match that of normal Python slices. The start position is included, the end position is excluded.
 
-Value-based slices will be stricly inclusive, with both the start and end values included. This behaviour differs from normal Python slices but is in common with pandas.
+Value-based slices will be strictly inclusive, with both the start and end values included. This behaviour differs from normal Python slices but is in common with pandas.
 
 Just as for normal Python slices, we do not need to provide the ability to control the include/exclude behaviour for slicing.
 

docs/src/common_links.inc

@@ -6,6 +6,7 @@
 .. _flake8: https://flake8.pycqa.org/en/stable/
 .. _.flake8.yml: https://github.com/SciTools/iris/blob/main/.flake8
 .. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris
+.. _codespell: https://github.com/codespell-project/codespell
 .. _conda: https://docs.conda.io/en/latest/
 .. _contributor: https://github.com/SciTools/scitools.org.uk/blob/master/contributors.json
 .. _core developers: https://github.com/SciTools/scitools.org.uk/blob/master/contributors.json

docs/src/community/iris_xarray.rst

@@ -11,7 +11,7 @@ you can be prepared, and to help you choose the best package for your use case.
 Overall Experience
 ------------------
 
-Iris is the more specialised package, focussed on making it as easy
+Iris is the more specialised package, focused on making it as easy
 as possible to work with meteorological and climatological data. Iris
 is built to natively handle many key concepts, such as the CF conventions,
 coordinate systems and bounded coordinates. Iris offers a smaller toolkit of

docs/src/conf.py

@@ -81,7 +81,7 @@ def autolog(message):
 # add some sample files from the developers guide..
 sys.path.append(os.path.abspath(os.path.join("developers_guide")))
 
-# why isnt the iris path added to it is discoverable too?  We dont need to,
+# why isn't the iris path added to it is discoverable too?  We dont need to,
 # the sphinext to generate the api rst knows where the source is.  If it
 # is added then the travis build will likely fail.
 
@@ -157,7 +157,7 @@ def _dotv(version):
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx.ext.napoleon",
-    "sphinx_panels",
+    "sphinx_design",
     "sphinx_gallery.gen_gallery",
     "matplotlib.sphinxext.mathmpl",
     "matplotlib.sphinxext.plot_directive",
@@ -167,9 +167,7 @@ def _dotv(version):
     autolog("Skipping the API docs generation (SKIP_API=1)")
 else:
     # better api documentation (custom)
-    extensions.extend(
-        ["custom_class_autodoc", "custom_data_autodoc", "generate_package_rst"]
-    )
+    extensions.extend(["custom_data_autodoc", "generate_package_rst"])
 
 # -- panels extension ---------------------------------------------------------
 # See https://sphinx-panels.readthedocs.io/en/latest/
@@ -239,11 +237,11 @@ def _dotv(version):
 # See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 
 extlinks = {
-    "issue": ("https://github.com/SciTools/iris/issues/%s", "Issue #"),
-    "pull": ("https://github.com/SciTools/iris/pull/%s", "PR #"),
+    "issue": ("https://github.com/SciTools/iris/issues/%s", "Issue #%s"),
+    "pull": ("https://github.com/SciTools/iris/pull/%s", "PR #%s"),
     "discussion": (
         "https://github.com/SciTools/iris/discussions/%s",
-        "Discussion #",
+        "Discussion #%s",
     ),
 }
 

docs/src/developers_guide/contributing_benchmarks.rst

@@ -38,8 +38,8 @@ applications.
 * Results for a series of commits can be visualised for an intuitive
   understanding of when and why changes occurred.
 
-    .. image:: asv_example_images/commits.png
-       :width: 300
+  .. image:: asv_example_images/commits.png
+     :width: 300
 
 * Parameterised benchmarks make it easy to visualise:
 

docs/src/developers_guide/contributing_ci_tests.rst

@@ -117,6 +117,14 @@ pull-requests given the `Iris`_ GitHub repository `.pre-commit-config.yaml`_.
 
 See the `pre-commit.ci dashboard`_ for details of recent past and active Iris jobs.
 
+.. note::
+
+  The `codespell`_ ``pre-commit`` hook checks the spelling of the whole codebase
+  and documentation.  This hook is configured in the ``[tool.codespell]`` section
+  of the ``pyproject.toml`` file.
+
+  Append to the ``ignore-words-list`` option any **valid words** that are
+  considered **not** a typo and should **not** be corrected by `codespell`_.
 
 .. _.pre-commit-config.yaml: https://github.com/SciTools/iris/blob/main/.pre-commit-config.yaml
 .. _pre-commit.ci dashboard: https://results.pre-commit.ci/repo/github/5312648

docs/src/developers_guide/gitwash/configure_git.rst

@@ -144,7 +144,7 @@ and it gives graph / text output something like this (but with color!)::
     | * 4aff2a8 - fixed bug 35, and added a test in test_bugfixes (2 weeks ago) [Hugo]
     |/
     * a7ff2e5 - Added notes on discussion/proposal made during Data Array Summit. (2 weeks ago) [Corran Webster]
-    * 68f6752 - Initial implimentation of AxisIndexer - uses 'index_by' which needs to be changed to a call on an Axes object - this is all very sketchy right now. (2 weeks ago) [Corr
+    * 68f6752 - Initial implementation of AxisIndexer - uses 'index_by' which needs to be changed to a call on an Axes object - this is all very sketchy right now. (2 weeks ago) [Corr
     *   376adbd - Merge pull request #46 from terhorst/main (2 weeks ago) [Jonathan Terhorst]
     |\
     | * b605216 - updated joshu example to current api (3 weeks ago) [Jonathan Terhorst]

docs/src/developers_guide/release.rst

@@ -173,7 +173,7 @@ Ensure that the artifacts are successfully uploaded and available on
 from PyPI::
 
     > conda deactivate
-    > conda env create --file ./requrements/ci/iris.yml
+    > conda env create --file ./requirements/iris.yml
     > . activate iris-dev
     > python -m pip install --no-deps scitools-iris
 

docs/src/further_topics/ugrid/operations.rst

@@ -53,7 +53,8 @@ structured formats and non-UGRID mesh formats.
 The objects created in this example will be used where possible in the
 subsequent example operations on this page.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -145,7 +146,8 @@ Creating a :class:`~iris.cube.Cube` is unchanged; the
 :class:`~iris.experimental.ugrid.Mesh` is linked via a
 :class:`~iris.experimental.ugrid.MeshCoord` (see :ref:`ugrid MeshCoords`):
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -206,7 +208,8 @@ The Iris saving process automatically detects if the :class:`~iris.cube.Cube`
 has an associated :class:`~iris.experimental.ugrid.Mesh` and automatically
 saves the file in a UGRID-conformant format:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -281,7 +284,8 @@ The :func:`iris.experimental.ugrid.save_mesh` function allows
 :class:`~iris.experimental.ugrid.Mesh`\es to be saved to file without
 associated :class:`~iris.cube.Cube`\s:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -352,7 +356,8 @@ loading a file remains **optional**. To load UGRID data from a file into the
 Iris mesh data model, use the
 :const:`iris.experimental.ugrid.PARSE_UGRID_ON_LOAD` context manager:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -372,7 +377,8 @@ All the existing loading functionality still operates on UGRID-compliant
 data - :class:`~iris.Constraint`\s, callbacks, :func:`~iris.load_cube`
 etcetera:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -415,7 +421,8 @@ The :func:`iris.experimental.ugrid.load_mesh` and
 :class:`~iris.experimental.ugrid.Mesh`\es to be loaded from a file without
 creating any associated :class:`~iris.cube.Cube`\s:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -469,7 +476,8 @@ be added to API in the near future.
 This first example uses GeoVista to plot the ``face_cube`` that we created
 earlier:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -539,7 +547,8 @@ earlier:
 
 Here's another example using a global cubed-sphere data set:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -614,7 +623,8 @@ therefore set to return an :class:`~iris.coords.AuxCoord` instead - breaking
 the link between :class:`~iris.cube.Cube` and
 :class:`~iris.experimental.ugrid.Mesh`:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -657,7 +667,8 @@ mesh, we then reconstruct a :class:`~iris.experimental.ugrid.Mesh` from the
 ..
     Not using doctest here as want to keep GeoVista as optional dependency.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -784,7 +795,8 @@ with the
 ..
     Not using doctest here as want to keep iris-esmf-regrid as optional dependency.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -880,11 +892,12 @@ Since calling a regridder is usually a lot faster than initialising, reusing
 regridders can save a lot of time. We can demonstrate the reuse of the
 previously initialised regridder:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
-        # Extract a different cube defined on te same Mesh.
+        # Extract a different cube defined on the same Mesh.
         >>> mesh_cube2 = mesh_cubes.extract_cube("precipitation_flux")
         >>> print(mesh_cube2)
         precipitation_flux / (kg m-2 s-1)   (-- : 1; -- : 13824)

docs/src/further_topics/ugrid/other_meshes.rst

@@ -27,7 +27,8 @@ To represent the Voronoi Polygons as faces, the corner coordinates will be used
 as the **nodes** when creating the Iris
 :class:`~iris.experimental.ugrid.mesh.Mesh`.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -115,7 +116,8 @@ as the **nodes** when creating the Iris
 :class:`~iris.experimental.ugrid.mesh.Mesh`.
 
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -253,7 +255,8 @@ To make an unstructured cube, the data must be 'flattened' to convert the given
 dimensions into a single mesh dimension.  Since Iris cubes don't support a "reshape" or
 "flatten" operations, we create a new cube from the flattened data.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python