Keep the signature anchor when :noindex: is set - #112
Open
ggiesen wants to merge 2 commits into
Open
Conversation
HTTPResource.add_target_and_index() appends the per-page anchor unconditionally and only gates the global route registration behind the noindex option, but ObjectDescription.run() skips the whole method when the option is set, so the anchor (and the HTML permalink) is dropped along with the registration and deep links into the page stop working. Anchors are per-document ids and cannot collide across pages; only the global registration can produce duplicate-route warnings (which are order-dependent in parallel builds, where merge_domaindata detects them). Handle the option in run() instead: pop it so the base class calls add_target_and_index(), keep the anchor, and skip only the registration. The informational noindex attribute on the desc node is preserved. Tested against Sphinx 6.2.1, 7.0.1, 7.4.7 and 8.1.3.
1 task
Documentation build overview
|
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.
Fixes #111.
add_target_and_index()already expresses the intended split - the per-page anchor is appended unconditionally and only the global route registration is gated behind:noindex:- butObjectDescription.run()skips the whole method when the option is set (at least since Sphinx 2.4.5), so the anchor and the HTML permalink were dropped along with the registration.Handle the option in
HTTPResource.run()instead: record it, pop it before running the base class (soadd_target_and_index()is called), keep the anchor, and gate only the registration. The informationalnoindex/no-indexattributes on thedescnode are preserved. On Sphinx 7.2+ the pop also happens before the base class normalizes the legacy spelling intono-index, so behaviour is identical across the supported range.Anchors are per-document ids, so restoring them cannot introduce collisions; only the global registration participates in
merge_domaindata(), which is where duplicate routes are (order-dependently) detected in parallel builds.Includes a build-level test covering both halves: the
:noindex:'d copy of a route documented on another page keeps itspost--demoanchor, and the domain data contains only the canonical page's registration. The anchor assertion fails without the fix; the registration assertion passes with and without, matching the analysis.Validated with
pytest(full suite) andsphinx-build -W -b html docson Sphinx 8.1.3 (the locked dev version), and the new tests additionally against Sphinx 6.2.1, 7.0.1, and 7.4.7.Real-world motivation: saltstack/salt documents overlapping routes on three pages and hit nondeterministic
duplicate HTTP post method definitionfailures in-W -j autoCI builds (saltstack/salt#69724);:noindex:on the non-canonical copies fixes that but currently costs the anchors, which this change makes unnecessary to trade away.