DOCS: Add gallery carousel to docs homepage

docs/src/_static/theme_override.css

@@ -26,3 +26,7 @@ ul.squarelist {
   text-indent: 1em;
   padding-left: 5em;
 }
+
+.center {
+    text-align: center;
+}

docs/src/conf.py

@@ -19,6 +19,8 @@
 
 """Config for sphinx."""
 
+import ast
+import contextlib
 import datetime
 from importlib.metadata import version as get_version
 from inspect import getsource
@@ -29,6 +31,7 @@
 from subprocess import run
 import sys
 from tempfile import gettempdir
+import textwrap
 from urllib.parse import quote
 import warnings
 
@@ -412,12 +415,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 +446,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/index.rst

@@ -15,6 +15,7 @@ representations become unwieldy and inefficient.
 
 For more information see :ref:`why_iris`.
 
+
 .. grid:: 3
 
     .. grid-item-card::
@@ -128,6 +129,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,7 +81,7 @@ This document explains the changes made to Iris for this release
 📚 Documentation
 ================
 
-#. N/A
+#. `@tkknight`_ added a gallery carousel to the documentation homepage. (:pull:`6884`)
 
 
 💼 Internal

requirements/py311.yml

@@ -56,7 +56,8 @@ dependencies:
   - sphinx-copybutton
   - sphinx-gallery >=0.11.0
   - sphinx-design
-  - pydata-sphinx-theme >=0.13.0
+  # Pinned reason: https://github.com/SciTools/iris/issues/6885
+  - pydata-sphinx-theme !=0.16.0,!=0.16.1,<0.16.2
 
 # Temporary minimum pins.
 # See https://github.com/SciTools/iris/pull/5051

requirements/py312.yml

@@ -56,7 +56,8 @@ dependencies:
   - sphinx-copybutton
   - sphinx-gallery >=0.11.0
   - sphinx-design
-  - pydata-sphinx-theme >=0.13.0
+  # Pinned reason: https://github.com/SciTools/iris/issues/6885
+  - pydata-sphinx-theme !=0.16.0,!=0.16.1,<0.16.2
 
 # Temporary minimum pins.
 # See https://github.com/SciTools/iris/pull/5051

requirements/py313.yml

@@ -56,7 +56,8 @@ dependencies:
   - sphinx-copybutton
   - sphinx-gallery >=0.11.0
   - sphinx-design
-  - pydata-sphinx-theme >=0.13.0
+  # Pinned reason: https://github.com/SciTools/iris/issues/6885
+  - pydata-sphinx-theme !=0.16.0,!=0.16.1,<0.16.2
 
 # Temporary minimum pins.
 # See https://github.com/SciTools/iris/pull/5051