docs: fix dead heading anchors and fail the docs build on warnings - #2476
Open
NoahKusaba wants to merge 3 commits into
Open
NoahKusaba wants to merge 3 commits into
NoahKusaba wants to merge 3 commits into
Conversation
myst_heading_anchors was never set, so MyST emitted no heading ids and every file.md#heading link 404'd on the published site (they resolve on GitHub). Set it, and fix the other warnings: a short title overline in index.rst, a page starting at H2, and a link to a directory rather than a document. docs/build.sh now builds with -W --keep-going so a broken cross-reference fails instead of shipping. sphinx-build goes from 16 warnings to 0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
This was referenced Sep 22, 2026
andygrove
reviewed
Sep 22, 2026
|
|
||
| rm -rf build | ||
| make html | ||
| SPHINXOPTS="-W --keep-going" make html |
Member
There was a problem hiding this comment.
I don't think we should fail the docs build on warnings unless we have a PR check to ensure that we don't merge PRs that introduce warnings. Our docs would just stop getting published in CI
Contributor
Author
There was a problem hiding this comment.
Agreed. As it stood, the first warning to land would have silently stopped the site publishing. I've changed it so warnings are caught on the PR and never block publishing:
docs.yamlnow also runs on pull requests that touch the docs, failing on warnings and skipping theasf-sitecheckout and push.- The deploy on
mainpublishes even with warnings, since one can still sneak in when two PRs are only broken together. build.shstays strict by default so local builds catch them, andSPHINXOPTSoverrides it (the deploy passes it empty).
…on them Failing the docs build on warnings only in the deploy job would stop the site from publishing, with nothing flagging the PR that caused it. Build the docs on pull requests that touch them, failing on warnings, and skip the asf-site checkout and push there. The deploy on main publishes regardless, since a warning can still reach main when two PRs are only broken together. build.sh stays strict by default, so local builds catch warnings, and takes SPHINXOPTS to override it. The push and pull_request triggers share one path list. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
2 participants
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.
Rationale for this change
Every intra-doc anchor link is dead on the published site.
myst_heading_anchorswas never set, so MyST emits no heading ids and allfile.md#headinglinks 404. They resolve on GitHub, which is why nobody noticed.sphinx-buildonmainreports 16 warnings.What changes are included in this PR?
myst_heading_anchors = 4indocs/source/conf.py. This fixes the 13 dead cross-references and changes how every Markdown page renders (heading ids are now emitted).index.rst,code-organization.mdstarting at H2, and a link inintroduction.mdto a directory rather than a document.docs/build.shis strict by default for local builds. The deploy onmainstill publishes if a warning slips through, so the site never stops updating.Are there any user-facing changes?
Links on the published docs site that 404 today will work. For contributors, docs PRs now fail CI on warnings, and so does a local
./build.sh.Verified:
sphinx-build -W --keep-goingis clean, 0 warnings (16 onmain).Note: this and the ruff PR both touch
docs/source/conf.pyon adjacent lines, so whichever lands second may need a trivial rebase.Split out of #2438 to make it easier to review.
🤖 Generated with Claude Code