docs: fall back to vendored intersphinx inventories - #376
Merged
Merged
Conversation
The strict PR docs build (-W) fails whenever one of the six upstream inventories is unreachable; a docs.python.org outage (503 on every URL) is failing build-docs on every open PR. List a vendored copy under docs/_inventories/ after each upstream location, as GPJax does: intersphinx uses the first that loads and logs only info when the upstream one fails, so the build stays green and links still resolve. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015fagcMeo1LmLG2Dg3NybmQ
thomaspinder
enabled auto-merge
October 1, 2026 09:11
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
build-docsfails on every PR while docs.python.org is down. The site returns503 Service Unavailableon every URL, includinghttps://docs.python.org/3/objects.inv. Intersphinx downloads that inventory, together with five others, on every build. The PR build runssphinx-build -W(make docs-ci), and an unreachable inventory is a warning, so the build fails. That warning has no type, sosuppress_warningscannot target it. Any of the six sites having a bad hour blocks every PR (it is blocking #375 now).Solution
Use the fallback that GPJax already uses. Each
intersphinx_mappingentry lists the upstream inventory first and then a vendored copy indocs/_inventories/. If the upstream fetch fails and the vendored copy loads, intersphinx logs only info, so the build stays green under-Wand the links still resolve.The vendored inventories:
numpy.invpandas.invarviz.invpymc.invmatplotlib.invpython.invThe cost is that the vendored copies go stale. This only affects builds where the upstream fetch failed. The
docs/conf.pycomment says how to refresh them.Verification
I ran two throwaway Sphinx 9.0.4 builds with
-W --keep-goingwhile docs.python.org was returning 503:failed to reach any of the inventories ... 503 Server Error, "1 warning (with warnings treated as errors)". This is the failure CI hits.str,datetime.datetime,numpy.ndarray,pandas.DataFrame,matplotlib.pyplot.plotandpymc.sampleall resolve to their upstream pages.All six inventories decode, with between 309 and 19,317 entries each.
ruff check,ruff format --checkand the repo's prek hooks pass on the changed files, andidentifytags the.invfiles as binary, so the text hooks skip them.🤖 Generated with Claude Code
https://claude.ai/code/session_015fagcMeo1LmLG2Dg3NybmQ