You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@datafusion.apache.org by "NoahKusaba (via GitHub)" <gi...@apache.org> on 2026/09/22 19:53:57 UTC

[PR] docs: fix dead heading anchors and fail the docs build on warnings [datafusion-ballista]

NoahKusaba opened a new pull request, #2476:
URL: https://github.com/apache/datafusion-ballista/pull/2476

   # Rationale for this change
   
   Every intra-doc anchor link is dead on the published site. `myst_heading_anchors` was never set, so MyST emits no heading ids and all `file.md#heading` links 404. They resolve on GitHub, which is why nobody noticed. `sphinx-build` on `main` reports 16 warnings.
   
   # What changes are included in this PR?
   
   - Set `myst_heading_anchors = 4` in `docs/source/conf.py`. This fixes the 13 dead cross-references and changes how every Markdown page renders (heading ids are now emitted).
   - Fix the remaining three warnings: a short title overline in `index.rst`, `code-organization.md` starting at H2, and a link in `introduction.md` to a directory rather than a document.
   - `docs/build.sh`, which the docs deploy workflow runs, now builds with `-W --keep-going`, so a broken cross-reference fails the build instead of shipping.
   
   # Are there any user-facing changes?
   
   Links on the published docs site that 404 today will work. For contributors, the docs build now fails on warnings.
   
   Verified: `sphinx-build -W --keep-going` is clean, 0 warnings (16 on `main`).
   
   Note: this and the ruff PR both touch `docs/source/conf.py` on 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](https://claude.com/claude-code)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] docs: fix dead heading anchors and fail the docs build on warnings [datafusion-ballista]

Posted by "NoahKusaba (via GitHub)" <gi...@apache.org>.
NoahKusaba commented on code in PR #2476:
URL: https://github.com/apache/datafusion-ballista/pull/2476#discussion_r4078028986


##########
docs/build.sh:
##########
@@ -18,4 +18,4 @@
 # under the License.
 
 rm -rf build
-make html
+SPHINXOPTS="-W --keep-going" make html

Review 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.yaml` now also runs on pull requests that touch the docs, failing on warnings and skipping the `asf-site` checkout and push.
   - The deploy on `main` publishes even with warnings, since one can still sneak in when two PRs are only broken together.
   - `build.sh` stays strict by default so local builds catch them, and `SPHINXOPTS` overrides it (the deploy passes it empty).
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] docs: fix dead heading anchors and fail the docs build on warnings [datafusion-ballista]

Posted by "NoahKusaba (via GitHub)" <gi...@apache.org>.
NoahKusaba closed pull request #2476: docs: fix dead heading anchors and fail the docs build on warnings
URL: https://github.com/apache/datafusion-ballista/pull/2476


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] docs: fix dead heading anchors and fail the docs build on warnings [datafusion-ballista]

Posted by "andygrove (via GitHub)" <gi...@apache.org>.
andygrove commented on code in PR #2476:
URL: https://github.com/apache/datafusion-ballista/pull/2476#discussion_r4076242373


##########
docs/build.sh:
##########
@@ -18,4 +18,4 @@
 # under the License.
 
 rm -rf build
-make html
+SPHINXOPTS="-W --keep-going" make html

Review 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



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org