fix(docs-autogen): scale source-link icon with heading font size

mdxify hardcodes `style="width: 14px; height: 14px;"` on the GitHub
Icon component.  Inline styles win over the stylesheet, so the icon
rendered at a fixed 14 px regardless of whether it appeared in an h2,
h3, or h4 heading.

Add a `normalize_icon_size` pass to decorate_api_mdx.py that replaces
the pixel dimensions with `0.85em` so the icon scales with the
surrounding heading's font size.  Remove the now-redundant CSS
width/height rules on `article h* sup svg` — the inline style is the
single source of truth for icon sizing.

Also add a mypy override to suppress the pre-existing import-not-found
error for `cpex`, a private optional dependency not available in all
environments.

Assisted-by: Claude Code

Author: planetf1

docs/src/css/custom.css

@@ -115,16 +115,10 @@ pre code {
   font-weight: 600;
 }
 
-/* API headings: inline GitHub source icon — de-superscript and scale to text size */
+/* API headings: inline GitHub source icon — de-superscript; size set via em inline style */
 article h2 sup,
 article h3 sup,
 article h4 sup {
   vertical-align: middle;
   font-size: 1em;
 }
-article h2 sup svg,
-article h3 sup svg,
-article h4 sup svg {
-  width: 0.9em;
-  height: 0.9em;
-}

pyproject.toml

@@ -312,6 +312,11 @@ disable_error_code = [
     "import-not-found",
 ]
 
+[[tool.mypy.overrides]]
+# cpex is a private optional dependency not available in all environments
+module = "cpex.*"
+ignore_missing_imports = true
+
 
 # -----------------------------
 # Codespell - Spell Checking

tooling/docs-autogen/decorate_api_mdx.py

@@ -11,6 +11,7 @@
 
 Decoration passes (applied in order per file):
 1. fix_source_links      — correct GitHub blob URLs to versioned tags
+1b. normalize_icon_size  — replace mdxify's hardcoded 14px icon style with em units
 2. inject_preamble       — add per-module introductory text
 3. inject_sidebar_fix    — insert SidebarFix Mintlify component
 4. escape_mdx_syntax     — escape {{ }} in code blocks so MDX doesn't treat them as JSX
@@ -123,6 +124,32 @@ def replace_md(match):
     return content
 
 
+# =========================
+# Icon size normalisation
+# =========================
+
+_ICON_PX_RE = re.compile(
+    r'(<Icon\b[^>]*\bstyle=")width:\s*\d+px;\s*height:\s*\d+px;("[^>]*/?>)'
+)
+
+
+def normalize_icon_size(content: str) -> str:
+    """Replace mdxify's hardcoded pixel icon sizes with em units.
+
+    mdxify emits ``style="width: 14px; height: 14px;"`` on source-link Icon
+    components.  Inline styles take priority over the stylesheet, so the icon
+    renders at a fixed 14 px regardless of heading level.  Swapping to ``em``
+    units lets the icon scale with the surrounding heading font-size.
+
+    Args:
+        content: MDX file content.
+
+    Returns:
+        Content with pixel icon dimensions replaced by ``0.85em``.
+    """
+    return _ICON_PX_RE.sub(r"\g<1>width: 0.85em; height: 0.85em;\g<2>", content)
+
+
 # =========================
 # RST double-backtick normalisation
 # =========================
@@ -856,6 +883,9 @@ def process_mdx_file(
     # Step 1: Fix GitHub source links
     text = fix_source_links(text, version)
 
+    # Step 1b: Replace mdxify's hardcoded 14px icon sizes with em units
+    text = normalize_icon_size(text)
+
     # Step 2: Inject preamble (docstring cache text may also contain RST notation;
     # inject_preamble runs after normalize so the injected text needs a second pass)
     text = inject_preamble(text, module_path, docstring_cache)