fix(35-S6): retry intersphinx inventory fetches on transient network errors

Author: gsvgit

docs/conf.py

@@ -229,6 +229,32 @@
     "pyformlang": ("https://pyformlang.readthedocs.io/en/latest/", None),
 }
 
+# CI runners occasionally drop outbound connections mid-fetch (2026-09-16:
+# networkx.org reset the connection, leaving every networkx cross-reference
+# unresolved and failing the build under the no-warnings policy). Retry
+# transient connection errors; when all attempts fail, the error propagates
+# and the build still fails.
+import time as _time
+
+from requests.exceptions import ConnectionError as _RequestsConnectionError
+from requests.exceptions import Timeout as _RequestsTimeout
+from sphinx.util import requests as _sphinx_requests
+
+_orig_intersphinx_get = _sphinx_requests.get
+
+
+def _get_with_retries(url, *args, retries=3, backoff=2.0, **kwargs):
+    for attempt in range(retries + 1):
+        try:
+            return _orig_intersphinx_get(url, *args, **kwargs)
+        except (_RequestsConnectionError, _RequestsTimeout):
+            if attempt == retries:
+                raise
+            _time.sleep(backoff * (attempt + 1))
+
+
+_sphinx_requests.get = _get_with_retries
+
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 default_role = "obj"

docs/developer.rst

@@ -108,6 +108,9 @@ HTML, checking links) live in :file:`docs/README.md`. Two policies matter:
 - **Full link check.** ``sphinx-build -b linkcheck`` verifies every local
   target and external URL (two documented exceptions in
   :file:`docs/conf.py`); it exits non-zero on broken or timed-out links.
+- **Resilient inventory fetches.** Intersphinx inventories are fetched with
+  retries on transient connection errors (:file:`docs/conf.py`); a persistent
+  failure still warns and fails the build.
 
 Both the build and the link check run in CI on every push and pull request
 (:file:`.github/workflows/docs.yml`).

tasks/detailed_plan.md

@@ -89,3 +89,24 @@ plan records only what is specific to this run.
   `[5.0.0]` changelog section.
 - Prepend `[done] ` to the task 35 line in `tasks/tasks.md` (local commit on
   `dev`; pushed with the next dev push — the release itself is already out).
+
+### S6: Make intersphinx inventory fetches resilient to transient network errors
+
+Added 2026-09-16 at the merge gate (user: "CI report set of warnings ... Fix
+it"). The first CI run on `20a181a` failed its Docs build because the runner's
+connection to `networkx.org` was reset while fetching the intersphinx
+inventory; with the inventory missing, every `nx.MultiDiGraph` cross-reference
+went unresolved and failed the build under the no-warnings policy. A second
+run of the same commit passed — the failure was a transient network flake, not
+a docs defect.
+
+**Code:** `docs/conf.py` (retry wrapper around `sphinx.util.requests.get`)
+**Tests:** skip — build configuration only; verified by a clean docs build
+**Docs:** `docs/developer.rst` ("Docs build and deploy" section)
+
+**Spec:**
+- Retry only transient connection errors (`ConnectionError`, `Timeout`); a
+  final failure propagates, so the warning still fires and the build still
+  fails — no suppression.
+- Note the behavior in the "Docs build and deploy" section of
+  `docs/developer.rst`.