[ac1982]

Fixes #58.

Register the routingtable label in env-before-read-docs, before Sphinx starts parallel readers. With the current doctree-read callback the label is created in worker environments, but the standard domain only merges labels targeting source documents. Its target, the generated http-routingtable page, is therefore discarded.

The existing label and anonymous-label entries are unchanged. Added a build-level regression for implicit and explicit-title references, target HTML and inventory entries across clean, incremental and unchanged builds with one and two workers. Includes a changelog entry.

Validation on Python 3.12 with both Sphinx 9.1.0 and minimum 8.1.3:

• Full suite: 13 passed, one wheel smoke skipped; wheel smoke separately enabled and passed.
• New regression test (tests/websocket_test.py) applied to the original source: its HTTP-only fixture passes with one reader and fails with two readers because routingtable is undefined. With this fix, both reader settings pass. This is separate from building the project’s own documentation.
• Warning-as-error project HTML builds pass in serial mode. HTTP-only parallel regression builds also pass. Project-wide -j2 on 8.1.3 warns about the separate autohttp.bottle extension's undeclared parallel safety.

The remaining Python-version tox matrix and external linkcheck were not run.

[read-the-docs-community]

Documentation build overview

📚 sphinxcontrib-httpdomain | 🛠️ Build #35158198 | 📁 Comparing b2cdd6f against latest (32c2156)

  🔍 Preview build  

1 file changed

± index.html

[stevepiercy]

@AstraLuma would you like to review this PR that proposes to fix the issue you opened?

[stevepiercy]

@ac1982 thank you for the PR and your first contribution!

This PR introduces a regression that causes warnings.

$ export SRC="/path/to/my/checkout"
$ source .venv/bin/activate
$ make clean; sphinx-build -j auto -n $SRC/docs $SRC/_build/html
cd ./docs/ && rm -rf ../_build/
Running Sphinx v9.1.0
loading translations [en]... done
making output directory... done
loading intersphinx inventory 'sphinx' from https://www.sphinx-doc.org/en/master/objects.inv ...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: the sphinxcontrib.autohttp.bottle extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... 
Writing evaluated template result to /docs/_build/html/_static/basic.css
Writing evaluated template result to /docs/_build/html/_static/language_data.js
Writing evaluated template result to /docs/_build/html/_static/documentation_options.js
Writing evaluated template result to /docs/_build/html/_static/sphinxdoc.css
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
/docs/index.rst:34: WARNING: py:mod reference target not found: sphinxcontrib.autohttp [ref.mod]
/docs/index.rst:50: WARNING: py:data reference target not found: extensions [ref.data]
/docs/index.rst:334: WARNING: rst:dir reference target not found: get [ref.dir]
/docs/index.rst:761: WARNING: py:data reference target not found: extensions [ref.data]
/docs/index.rst:792: WARNING: py:func reference target not found: create_app [ref.func]
/docs/index.rst:805: WARNING: py:func reference target not found: user [ref.func]
/docs/index.rst:805: WARNING: py:func reference target not found: post [ref.func]
/docs/index.rst:805: WARNING: py:func reference target not found: friends [ref.func]
/docs/index.rst:830: WARNING: py:func reference target not found: admin [ref.func]
/docs/index.rst:830: WARNING: py:func reference target not found: admin_login [ref.func]
/docs/index.rst:903: WARNING: py:attr reference target not found: __doc__ [ref.attr]
/docs/index.rst:1002: WARNING: py:data reference target not found: extensions [ref.data]
/docs/index.rst:1029: WARNING: py:func reference target not found: create_app [ref.func]
/docs/index.rst:1042: WARNING: py:func reference target not found: user [ref.func]
/docs/index.rst:1042: WARNING: py:func reference target not found: post [ref.func]
/docs/index.rst:1042: WARNING: py:func reference target not found: friends [ref.func]
/docs/index.rst:1065: WARNING: py:func reference target not found: admin [ref.func]
/docs/index.rst:1065: WARNING: py:func reference target not found: admin_login [ref.func]
/docs/index.rst:1076: WARNING: py:attr reference target not found: __doc__ [ref.attr]
/docs/index.rst:1089: WARNING: py:data reference target not found: extensions [ref.data]
/docs/index.rst:1123: WARNING: py:func reference target not found: get [ref.func]
/docs/index.rst:1123: WARNING: py:func reference target not found: post [ref.func]
/docs/index.rst:1123: WARNING: py:class reference target not found: User [ref.class]
/docs/index.rst:1123: WARNING: py:class reference target not found: RequestHandler [ref.class]
/docs/index.rst:1123: WARNING: py:func reference target not found: get [ref.func]
/docs/index.rst:1123: WARNING: py:class reference target not found: Friend [ref.class]
/docs/index.rst:1123: WARNING: py:class reference target not found: RequestHandler [ref.class]
/docs/index.rst:1147: WARNING: py:func reference target not found: admin [ref.func]
/docs/index.rst:1147: WARNING: py:func reference target not found: admin_login [ref.func]
/docs/index.rst:1158: WARNING: py:attr reference target not found: __doc__ [ref.attr]
/docs/index.rst:1242: WARNING: py:mod reference target not found: sphinxcontrib.autohttp [ref.mod]
/docs/index.rst:1242: WARNING: py:mod reference target not found: sphinxcontrib [ref.mod]
/CHANGELOG.rst:212: WARNING: py:mod reference target not found: sphinxcontrib.autohttp [ref.mod]
/CHANGELOG.rst:292: WARNING: py:mod reference target not found: autohttp.tornado [ref.mod]
/CHANGELOG.rst:322: WARNING: py:mod reference target not found: sphinxcontrib.autohttp [ref.mod]
/CHANGELOG.rst:341: WARNING: py:class reference target not found: flask.views.MethodView [ref.class]
/CHANGELOG.rst:364: WARNING: py:data reference target not found: http_index_ignore_prefixes [ref.data]
/CHANGELOG.rst:385: WARNING: py:attr reference target not found: flask.Flask.static_path [ref.attr]
/CHANGELOG.rst:385: WARNING: py:attr reference target not found: flask.Flask.static_url_path [ref.attr]

generating indices... genindex http-routingtable py-modindex websocket-routingtable done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 41 warnings.

The HTML pages are in docs/_build/html.

This PR proposes a trade-off that I think is worse than the current situation. Can you suggest an alternative implementation?

[ac1982]

Thank you for checking this. I reproduced your command with Sphinx 9.1.0 on both the unmodified base (32c21562d85d3accf4f06a0a88a1b24f92089ce5) and this PR (b2cdd6f3d53b1430a8540989202c72427bce5a7c), using separate clean output directories and explicitly selecting each checkout's src via PYTHONPATH:

PYTHONPATH="$CHECKOUT/src" "$VENV/bin/python" -m sphinx \
  -E -j auto -n -b html "$CHECKOUT/docs" "$OUTPUT"

Both builds succeed with 41 warnings: the same two parallel-read warnings from autohttp.bottle and the same 39 missing-reference warnings. Comparing the warning messages produces no differences after normalizing source line numbers; the changelog references move by two lines because of the added release note. I also checked the imported module path to confirm the baseline build loaded the baseline source.

The original regression test uses an HTTP-only, three-document project so parallel reading actually runs (the project's own docs fall back to serial reading because of the bottle extension). On the base, its parallel build fails to resolve routingtable; this PR passes serial and parallel clean builds, changed-document rebuilds, and unchanged rebuilds on Sphinx 8.1.3 and 9.1.0.

I haven't changed the implementation in response to these warnings, since I could not reproduce a warning introduced by this patch. The existing standard-domain label registration remains in place; moving it before reader dispatch prevents the generated index label from being lost during worker-environment merging. builder-inited is another possible main-process registration point, but it would not address these existing documentation warnings either. If there is a different failure or environment difference I missed, I can investigate that separately.

[stevepiercy]

@ac1982 thanks for your quick response.

I made a mistake with the command, which I've corrected as follows:

$ make clean; sphinx-build -j auto -n $SRC/docs $SRC/_build/html

And I verified that you're correct. These commands return the same results before this PR and with it. However, your bullet point in your original description confused me:

• New regression on original source: serial passes, parallel fails with undefined-label warnings.

Can you explain what you mean by a "new regression", when its results are the same as before?

---

Regarding the fallback to serial read, that's covered in #15. I just updated that issue with a potential fix. I assume that parallel reads would be OK for all the builders.

Please let me know. Thank you!

[ac1982]

Thank you for verifying it. That was imprecise wording on my part: I meant “new regression test”, not a newly introduced regression. I've corrected the PR description.

The test builds a separate three-document fixture that enables only sphinxcontrib.httpdomain, so Sphinx can actually use parallel readers. Applied to the original source, that test passes with one reader and fails with two because the routingtable reference is undefined. With the patch, both pass, including incremental and unchanged rebuilds. The project's own documentation build is a different case: it enables the autohttp extensions and falls back to serial reading, so its warnings are unchanged.

Thanks for pointing me to #15. Declaring parallel_read_safe is a promise about concurrent reading, so I would first verify each autohttp extension's imports, registration/state, and generated directives in a multi-document build rather than infer safety from the warning disappearing. This PR's tests cover the HTTP domain's generated label; they do not establish parallel safety for all autohttp extensions or builders.

[stevepiercy]

@ac1982 thanks for the response. I'd like to let this wait for no more than one week to give other people a chance to review and give feedback or approve.

I also updated #15 with another requirement.