docs(sphinx) Reserve demo image space with aspect-ratio

why: The demo GIFs render as width:100% with no intrinsic size, so the
browser reserves no height until each GIF decodes and the page jumps as
you move through the sidebar. Sphinx only emits dimensions for :scale:,
and those come out as fixed pixels that distort the image on narrow
viewports.

what:
- Add an html-page-context hook stamping each demo <img> with
  width:100%; aspect-ratio:W/H, computed from the source GIF
- Reserves the correct box before load (no layout shift) while staying
  fluid and keeping lazy loading

Author: tony

docs/_ext/aspect_ratio.py

@@ -0,0 +1,64 @@
+"""Reserve demo image space via aspect-ratio so pages don't shift on load (CLS).
+
+Sphinx's HTML writer renders image ``:width:`` as an inline pixel style, which
+overrides the theme's ``height: auto`` and distorts responsive images. Instead
+this stamps each demo ``<img>`` with ``width:100%; aspect-ratio:W/H`` (computed
+from the source GIF), so the browser reserves the correct box before the image
+loads while keeping it fluid.
+"""
+
+from __future__ import annotations
+
+import re
+import typing as t
+from pathlib import Path
+
+from sphinx.util.images import get_image_size
+
+if t.TYPE_CHECKING:
+    from docutils import nodes
+    from sphinx.application import Sphinx
+
+_IMG = re.compile(r'<img\b[^>]*?\bsrc="[^"]+?/([^"/]+?\.gif)"[^>]*?/?>')
+_STYLE = re.compile(r'style="[^"]*"')
+_sizes: dict[str, tuple[int, int]] = {}
+
+
+def _index_sizes(app: Sphinx) -> None:
+    """Map each source GIF's basename to its intrinsic ``(width, height)``."""
+    for path in Path(app.srcdir).rglob("*.gif"):
+        size = get_image_size(path)
+        if size is not None:
+            _sizes[path.name] = size
+
+
+def _inject(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: dict[str, t.Any],
+    doctree: nodes.document | None,
+) -> None:
+    """Rewrite demo ``<img>`` tags to carry ``width:100%; aspect-ratio:W/H``."""
+    body = context.get("body")
+    if not body or "_images/" not in body:
+        return
+
+    def repl(match: re.Match[str]) -> str:
+        tag, name = match.group(0), match.group(1)
+        size = _sizes.get(name)
+        if size is None or "aspect-ratio" in tag:
+            return tag
+        style = f"width:100%;aspect-ratio:{size[0]}/{size[1]}"
+        if 'style="' in tag:
+            return _STYLE.sub(f'style="{style}"', tag)
+        return tag[:-1].rstrip("/") + f' style="{style}" />'
+
+    context["body"] = _IMG.sub(repl, body)
+
+
+def setup(app: Sphinx) -> dict[str, t.Any]:
+    """Register the aspect-ratio injector."""
+    app.connect("builder-inited", _index_sizes)
+    app.connect("html-page-context", _inject)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

docs/conf.py

@@ -38,6 +38,7 @@
     extra_extensions=[
         "sphinx_autodoc_api_style",
         "sphinx_autodoc_argparse.exemplar",
+        "aspect_ratio",
     ],
     intersphinx_mapping={
         "py": ("https://docs.python.org/", None),