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

* upstream/main:
  DOCS: Add gallery carousel to docs homepage (SciTools#6884)
  SPEC0 - support Python 3.12 to 3.14 (SciTools#6816)

Author: tkknight

.github/workflows/ci-tests.yml

@@ -35,18 +35,18 @@ jobs:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest"]
-        python-version: ["3.13"]
+        python-version: ["3.14"]
         session: ["doctest", "gallery"]
         include:
           - os: "ubuntu-latest"
-            python-version: "3.13"
+            python-version: "3.14"
             session: "tests"
             coverage: "--coverage"
           - os: "ubuntu-latest"
-            python-version: "3.12"
+            python-version: "3.13"
             session: "tests"
           - os: "ubuntu-latest"
-            python-version: "3.11"
+            python-version: "3.12"
             session: "tests"
 
     env:

.github/workflows/ci-wheels.yml

@@ -52,7 +52,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13", "3.14"]
         session: ["wheel"]
     env:
       ENV_NAME: "ci-wheels"

benchmarks/bm_runner.py

@@ -67,7 +67,7 @@ def _check_requirements(package: str) -> None:
 
 def _prep_data_gen_env() -> None:
     """Create or access a separate, unchanging environment for generating test data."""
-    python_version = "3.13"
+    python_version = "3.14"
     data_gen_var = "DATA_GEN_PYTHON"
     if data_gen_var in environ:
         echo("Using existing data generation environment.")

docs/src/_static/theme_override.css

@@ -50,4 +50,8 @@ ul.squarelist {
 .custom-body {
     text-align: left;
     margin-left: max(45px, 15%);
+}
+
+.center {
+    text-align: center;
 }

docs/src/conf.py

@@ -19,7 +19,10 @@
 
 """Config for sphinx."""
 
+import ast
+import contextlib
 import datetime
+import importlib
 from importlib.metadata import version as get_version
 from inspect import getsource
 import ntpath
@@ -29,6 +32,7 @@
 from subprocess import run
 import sys
 from tempfile import gettempdir
+import textwrap
 from urllib.parse import quote
 import warnings
 
@@ -219,6 +223,11 @@ def _dotv(version):
 autoclass_content = "both"
 modindex_common_prefix = ["iris"]
 
+# if geovista is not installed we need to mock the imports so the autodoc build works:
+if importlib.util.find_spec("geovista") is None:
+    autodoc_mock_imports = ["geovista", "pyvista"]
+
+
 # -- apidoc extension ---------------------------------------------------------
 # See https://github.com/sphinx-contrib/apidoc
 source_code_root = (Path(__file__).parents[2]).absolute()
@@ -283,7 +292,15 @@ def _dotv(version):
 
 # -- Doctest ("make doctest")--------------------------------------------------
 
-doctest_global_setup = "import iris"
+doctest_global_setup = """
+import iris
+
+# To handle conditional doctest skipping if geovista is not installed:
+try:
+    import geovista as gv
+except ImportError:
+    gv = None
+"""
 
 # -- Options for HTML output --------------------------------------------------
 
@@ -412,12 +429,14 @@ def reset_modules(gallery_conf, fname):
 )
 sys.path.insert(0, str(reset_modules_dir))
 
+GALLERY_CODE: str = "../gallery_code"
+GALLERY_DIRS: str = "generated/gallery"
 
 sphinx_gallery_conf = {
     # path to your example scripts
-    "examples_dirs": ["../gallery_code"],
+    "examples_dirs": GALLERY_CODE,
     # path to where to save gallery generated output
-    "gallery_dirs": ["generated/gallery"],
+    "gallery_dirs": GALLERY_DIRS,
     # filename pattern for the files in the gallery
     "filename_pattern": "/plot_",
     # filename pattern to ignore in the gallery
@@ -441,3 +460,133 @@ def reset_modules(gallery_conf, fname):
     "section": "Section %s",
     "table": "Table %s",
 }
+
+# ============================================================================
+# |                        Copyright GeoVista                                |
+# | Code from this point unto the termination banner is copyright GeoVista.  |
+# | Minimal code changes made to make it generic.                            |
+# |                                                                          |
+# | License details can be found at:                                         |
+# |    https://github.com/bjlittle/geovista/blob/main/LICENSE                |
+# ============================================================================
+
+# Source: https://github.com/bjlittle/geovista/blob/main/docs/src/conf.py
+
+
+def _bool_eval(*, arg: str | bool) -> bool:
+    """Sanitise to a boolean only configuration."""
+    if isinstance(arg, str):
+        with contextlib.suppress(TypeError):
+            arg = ast.literal_eval(arg.capitalize())
+
+    return bool(arg)
+
+
+def generate_carousel(
+    app: Sphinx,
+    fname: Path,
+    ncards: int | None = None,
+    margin: int | None = None,
+    width: int | None = None,
+) -> None:
+    """Generate and write the gallery carousel RST file."""
+    if ncards is None:
+        ncards = 3
+
+    if margin is None:
+        margin = 4
+
+    if width is None:
+        width = "25%"
+
+    base = Path(app.srcdir, *GALLERY_DIRS.split("/"))
+    cards_by_link = {}
+
+    card = r""".. card::
+    :img-background: {image}
+    :link: {link}
+    :link-type: ref
+    :width: {width}
+    :margin: {margin}
+    :class-card: align-self-center
+"""
+
+    # TODO @bjlittle: use Path.walk when python >=3.12
+    for root, _, files in os.walk(str(base)):
+        root = Path(root)  # noqa: PLW2901
+        if root.name == "images":
+            root_relative = root.relative_to(app.srcdir)
+            link_relative = root.parent.relative_to(app.srcdir)
+
+            for file in files:
+                path = Path(file)
+                if path.suffix == ".png":
+                    # generate the card "img-background" filename
+                    image = root_relative / path
+
+                    # generate the card "link" reference
+                    # remove numeric gallery image index e.g., "001"
+                    parts = path.stem.split("_")[:-1]
+                    link = parts[:2] + list(link_relative.parts) + parts[2:]
+                    link = f"{'_'.join(link)}.py"
+
+                    # needed in case a gallery filename has mixed case
+                    link = link.lower()
+
+                    kwargs = {
+                        "image": image,
+                        "link": link,
+                        "width": width,
+                        "margin": margin,
+                    }
+
+                    cards_by_link[link] = card.format(**kwargs)
+
+    # sort the cards by their link
+    cards = [cards_by_link[link] for link in sorted(cards_by_link.keys())]
+    cards = textwrap.indent("\n".join(cards), prefix=" " * 4)
+
+    # now, create the card carousel
+    carousel = f""".. card-carousel:: {ncards}
+
+{cards}
+
+.. rst-class:: center
+
+    :fa:`images` Gallery Carousel
+
+"""
+
+    # finally, write the rst for the gallery carousel
+    Path(app.srcdir, fname).write_text(carousel)
+
+
+def gallery_carousel(
+    app: Sphinx,
+    env: BuildEnvironment,  # noqa: ARG001
+    docnames: list[str],  # noqa: ARG001
+) -> None:
+    """Create the gallery carousel."""
+    # create empty or truncate existing file
+    fname = Path(app.srcdir, "gallery_carousel.txt")
+
+    with fname.open("w"):
+        pass
+
+    if _bool_eval(arg=app.builder.config.plot_gallery):
+        # only generate the carousel if we have a gallery
+        generate_carousel(app, fname)
+
+
+# ============================================================================
+# |                        END GeoVista copyright                            |
+# ============================================================================
+
+
+def setup(app: Sphinx) -> None:
+    """Configure sphinx application."""
+    # we require the output of this extension
+    app.setup_extension("sphinx_gallery.gen_gallery")
+
+    # register callback to generate gallery carousel
+    app.connect("env-before-read-docs", gallery_carousel)

docs/src/further_topics/ugrid/operations.rst

@@ -583,6 +583,7 @@ below:
     :icon: code
 
     .. doctest:: ugrid_operations
+        :skipif: gv is None
 
         >>> from geovista.geodesic import BBox
         >>> from iris import load_cube, sample_data_path

docs/src/index.rst

@@ -15,6 +15,11 @@ representations become unwieldy and inefficient.
 
 For more information see :ref:`why_iris`.
 
+<<<<<<< HEAD
+=======
+
+.. grid:: 3
+>>>>>>> upstream/main
 
 .. grid:: 1 1 2 2
     :gutter: 2
@@ -88,6 +93,9 @@ For more information see :ref:`why_iris`.
 Icons made by FreePik from `Flaticon <https://www.flaticon.com/>`_
 
 
+.. include:: gallery_carousel.txt
+
+
 .. _iris_support:
 
 Support

docs/src/whatsnew/latest.rst

@@ -81,8 +81,12 @@ This document explains the changes made to Iris for this release
 📚 Documentation
 ================
 
+<<<<<<< HEAD
 #. `@tkknight`_ reduced the space used on the documentation homepage by the quick
    link cards to allow for easier reading.  (:pull:`6886`)
+=======
+#. `@tkknight`_ added a gallery carousel to the documentation homepage. (:pull:`6884`)
+>>>>>>> upstream/main
 
 
 💼 Internal
@@ -99,13 +103,19 @@ This document explains the changes made to Iris for this release
 
 #. `@tkknight`_ removed flake8, we have ruff now instead.  (:pull:`6889`)
 
+#. `@trexfeathers`_ and `@ukmo-ccbunney`_ updated CI to support Python 3.14
+   inline with `SPEC0 Minimum Supported Dependencies`_. Note: `pyvista` (and
+   hence `geovista`) is not yet compatible with Python 3.14, so
+   `:module:~iris.experimental.geovista` is currently only available for
+   Python \<3.14.  (:pull:`6816`, :issue:`6775`)
+
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,
     core dev names are automatically included by the common_links.inc:
 
 .. _@hdyson: https://github.com/hdyson
 
-
+.. _SPEC0 Minimum Supported Dependencies: https://scientific-python.org/specs/spec-0000/
 
 .. comment
     Whatsnew resources in alphabetical order: