docs: don't fail -W builds when intersphinx inventories are unreachable

docs/conf.py

@@ -2,8 +2,13 @@
 
 from __future__ import annotations
 
+import logging
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(REPO_ROOT / "src"))
@@ -84,6 +89,35 @@
     "numpy": ("https://numpy.org/doc/stable", None),
     "scipy": ("https://docs.scipy.org/doc/scipy", None),
 }
+# Fail fast instead of hanging when an inventory host is unreachable.
+intersphinx_timeout = 30
+
+
+class _IgnoreUnreachableInventories(logging.Filter):
+    """Drop the intersphinx "failed to reach any of the inventories" warning.
+
+    GitHub runners intermittently cannot reach docs.scipy.org and friends. That
+    warning is emitted without a Sphinx warning ``type``, so it cannot be
+    silenced through ``suppress_warnings``; without this filter it turns
+    ``sphinx-build -W`` into a hard failure. Unresolved cross-references simply
+    render as plain text when an inventory is missing.
+    """
+
+    _PREFIX = "failed to reach any of the inventories"
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not str(record.msg).startswith(self._PREFIX)
+
+
+def setup(app: Sphinx) -> None:
+    """Install the intersphinx warning filter."""
+
+    # Sphinx prefixes its logger names with "sphinx."; the intersphinx logger
+    # has been "sphinx.sphinx.ext.intersphinx" through Sphinx 9.
+    logging.getLogger("sphinx.sphinx.ext.intersphinx").addFilter(
+        _IgnoreUnreachableInventories()
+    )
+
 
 html_theme = "furo"
 html_title = "jitr documentation"