Keep the signature anchor when :noindex: is set

[ggiesen]

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: - but ObjectDescription.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 (so add_target_and_index() is called), keep the anchor, and gate only the registration. The informational noindex/no-index attributes on the desc node are preserved. On Sphinx 7.2+ the pop also happens before the base class normalizes the legacy spelling into no-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 its post--demo anchor, 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) and sphinx-build -W -b html docs on 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 definition failures in -W -j auto CI 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.

[read-the-docs-community]

Documentation build overview

📚 sphinxcontrib-httpdomain | 🛠️ Build #34021804 | 📁 Comparing bb29faf against latest (1d96b0f)

  🔍 Preview build  

1 file changed

± index.html

[stevepiercy]

Thanks for reporting the issue and creating a PR. Sorry for the long delay to respond.

Do you have before and after examples as rendered HTML? It's not necessary, but it would help me have a complete understanding. Our PR preview docs on Read the Docs don't show any relevant diff.

Otherwise, this LGTM. I have a few PRs ahead of this to merge, then I'll handle any merge conflicts with CHANGES.rst.

[ggiesen]

Thanks Steve! Here's a concrete before/after from the real case this came from. Salt's rest_wsgi page documents POST /, which is canonical on rest_cherrypy, so the wsgi copy is :noindex:'d -- one of ~10 shared routes across the netapi pages that were registering duplicate httpdomain entries and failing sphinx -j auto -W builds.

Rendered <dt> for that :noindex:'d POST /:

Before (2.0.0) -- no id, no permalink, so an in-page POST / link on that page goes nowhere:

<dt class="sig sig-object http"><span ...>POST</span><span ...>/</span></dt>

After (this PR):

<dt class="sig sig-object http" id="post--"><span ...>POST</span><span ...>/</span><a class="headerlink" href="#post--">...</a></dt>

id="post--" and the permalink are back, while the global registration stays gated (no duplicate-route warning).

Why the RTD preview shows no diff: httpdomain's own docs never document a route on two pages, so nothing there is :noindex:'d. Salt actually ships a small doc/_ext/salthttpanchors.py that monkeypatches this exact behaviour (pop noindex before run(), re-present it to add_target_and_index) to keep its anchors -- this PR makes that workaround unnecessary.