Flaky docs -W build: duplicate HTTP method definitions across netapi pages fail Prepare Release under -j auto

[ggiesen]

What happened?

The 3006.x Prepare Release job intermittently fails with:

WARNING: duplicate HTTP post method definition / in doc/ref/netapi/all/salt.netapi.rest_tornado.rst, other instance is in doc/ref/netapi/all/salt.netapi.rest_wsgi.rst
build finished with problems, 1 warning (with warnings treated as errors).
make: *** [Makefile:144: man] Error 1

(observed in run 28746163934, job "Prepare Release: 3006.27+40.gce6cefc130"). When it hits, the release patch artifact is never uploaded and every downstream job in the run (Documentation, Build Source Tarball, all Build Source Packages / onedir matrices) fails with "Artifact not found", so a single flaky warning takes out the whole run for the PR.

Root cause

tools docs man/html build with SPHINXOPTS=-W -j auto --keep-going (tools/docs.py). Three netapi doc pages document overlapping HTTP routes via docstrings: rest_cherrypy and rest_tornado share 9 routes (GET/POST /, GET/POST /login, GET /minions/(mid), POST /minions, GET /jobs/(jid), POST /run, GET /events, POST /hook), and rest_wsgi also documents POST /.

In sphinxcontrib-httpdomain (2.0.0, as pinned), the duplicate check only exists in merge_domaindata, which runs when -j parallel reader workers are merged; a serial build silently last-writer-wins. So the warning fires only when a chunk boundary happens to separate two of the colliding documents, which depends on chunk assignment and worker count -- hence flaky: most runs pass, some fail, unrelated to the PR's changes.

A side effect of the same collision: the HTTP routing index is nondeterministic today -- shared routes point at whichever page was read last (currently rest_tornado/rest_wsgi win over the canonical rest_cherrypy reference).

Fix

Add :noindex: to the colliding http: directives in salt/netapi/rest_tornado/saltnado.py and salt/netapi/rest_wsgi.py, keeping rest_cherrypy as the single indexed (canonical) instance of each route. :noindex: skips domain registration entirely (httpdomain only registers when 'noindex' not in self.options), so no route is ever registered twice and the merge collision becomes impossible under any chunking. Page content is unaffected -- the tornado/wsgi pages still render their endpoint documentation; the routes just stop being duplicate index/xref targets. There are no :http:<method>: cross-references anywhere in the docs or docstrings, so no links change.

Verified locally with the pinned docs.lock (sphinx 7.0.1, sphinxcontrib-httpdomain 2.0.0): before the change, the pickled build environment shows the shared routes registered by rest_tornado/rest_wsgi; after it, every route is registered exactly once, by rest_cherrypy. make man and make html with -W -j auto --keep-going build clean.

Type of salt install

Not applicable, CI/docs build.

Major version

3006.x

What supported OS are you seeing the problem on? Can select multiple. (If bug appears on an unsupported OS, please open a GitHub Discussion instead)

No response

salt --versions-report output

Not applicable, CI docs build (GitHub Actions ubuntu runners).