docs(sphinx_fonts): multi-subset support with unicode-range descriptors

why: Only the "latin" subset was downloaded. Characters outside basic
Latin (accented letters like ñ, ř, ž common in contributor names and
code comments) fell back to system fonts, breaking the typographic
consistency of IBM Plex.

what:
- Add _UNICODE_RANGES dict mapping Fontsource subset names to CSS
  unicode-range descriptors for latin, latin-ext, cyrillic,
  cyrillic-ext, greek, and vietnamese
- Add _unicode_range() lookup function with empty-string fallback
  for unknown subsets (omitting the descriptor = all codepoints)
- Support "subsets" (list) config key alongside legacy "subset" (str)
  in _on_builder_inited — iterates all subsets in the download loop
- Emit unicode-range in font_faces dict; template renders it in
  @font-face blocks so browsers only download subset files when
  characters from that range appear on the page (zero cost for pages
  that only use ASCII)
- Preload uses the first (primary) subset only — typically "latin"
- Update page.html template: conditional unicode-range line in
  @font-face blocks
- Add 8 tests: _unicode_range (4), multi-subset builder-inited (2),
  legacy subset backward compat (1), preload primary subset (1)

Author: tony

docs/_ext/sphinx_fonts.py

@@ -54,6 +54,57 @@ def _cdn_url(
     )
 
 
+# Unicode range descriptors per subset — tells the browser to only download
+# the file when characters from this range appear on the page.  Ranges are
+# from Fontsource / Google Fonts CSS (CSS unicode-range values).
+_UNICODE_RANGES: dict[str, str] = {
+    "latin": (
+        "U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6,"
+        " U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F,"
+        " U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215,"
+        " U+FEFF, U+FFFD"
+    ),
+    "latin-ext": (
+        "U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7,"
+        " U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,"
+        " U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB,"
+        " U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF"
+    ),
+    "cyrillic": ("U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116"),
+    "cyrillic-ext": (
+        "U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F"
+    ),
+    "greek": (
+        "U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF"
+    ),
+    "vietnamese": (
+        "U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169,"
+        " U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304,"
+        " U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB"
+    ),
+}
+
+
+def _unicode_range(subset: str) -> str:
+    """Return the CSS ``unicode-range`` descriptor for *subset*.
+
+    Falls back to an empty string for unknown subsets (omitting the
+    descriptor causes the browser to treat the face as covering all
+    codepoints, which is the correct fallback).
+
+    Parameters
+    ----------
+    subset : str
+        Fontsource subset name (e.g. ``"latin"``, ``"latin-ext"``).
+
+    Returns
+    -------
+    str
+        CSS ``unicode-range`` value, or ``""`` if unknown.
+    """
+    return _UNICODE_RANGES.get(subset, "")
+
+
 def _download_font(url: str, dest: pathlib.Path) -> bool:
     if dest.exists():
         logger.debug("font cached: %s", dest.name)
@@ -89,31 +140,36 @@ def _on_builder_inited(app: Sphinx) -> None:
         font_id = font["package"].split("/")[-1]
         version = font["version"]
         package = font["package"]
-        subset = font.get("subset", "latin")
-        for weight in font["weights"]:
-            for style in font["styles"]:
-                filename = f"{font_id}-{subset}-{weight}-{style}.woff2"
-                cached = cache / filename
-                url = _cdn_url(package, version, font_id, subset, weight, style)
-                if _download_font(url, cached):
-                    shutil.copy2(cached, fonts_dir / filename)
-                    font_faces.append(
-                        {
-                            "family": font["family"],
-                            "style": style,
-                            "weight": str(weight),
-                            "filename": filename,
-                        }
-                    )
+        # Accept "subsets" (list) or legacy "subset" (str).
+        subsets: list[str] = font.get("subsets", [font.get("subset", "latin")])
+        for subset in subsets:
+            for weight in font["weights"]:
+                for style in font["styles"]:
+                    filename = f"{font_id}-{subset}-{weight}-{style}.woff2"
+                    cached = cache / filename
+                    url = _cdn_url(package, version, font_id, subset, weight, style)
+                    if _download_font(url, cached):
+                        shutil.copy2(cached, fonts_dir / filename)
+                        font_faces.append(
+                            {
+                                "family": font["family"],
+                                "style": style,
+                                "weight": str(weight),
+                                "filename": filename,
+                                "unicode_range": _unicode_range(subset),
+                            }
+                        )
 
     preload_hrefs: list[str] = []
     preload_specs: list[tuple[str, int, str]] = app.config.sphinx_font_preload
     for family_name, weight, style in preload_specs:
         for font in fonts:
             if font["family"] == family_name:
                 font_id = font["package"].split("/")[-1]
-                subset = font.get("subset", "latin")
-                filename = f"{font_id}-{subset}-{weight}-{style}.woff2"
+                # Preload the first (primary) subset only — typically "latin".
+                subsets = font.get("subsets", [font.get("subset", "latin")])
+                primary = subsets[0] if subsets else "latin"
+                filename = f"{font_id}-{primary}-{weight}-{style}.woff2"
                 preload_hrefs.append(filename)
                 break
 

docs/_templates/page.html

@@ -13,6 +13,9 @@
     font-weight: {{ face.weight }};
     font-display: block;
     src: url("{{ pathto('_static/fonts/' + face.filename, 1) }}") format("woff2");
+    {%- if face.unicode_range %}
+    unicode-range: {{ face.unicode_range }};
+    {%- endif %}
   }
   {%- endfor %}
   {%- for fb in font_fallbacks|default([]) %}