Module omitted from index can be linked in Sphinx 8.0.2, fails in 8.1.3

[nedbat]

Describe the bug

In the coverage.py docs, I use .. module:: coverage in a few places. They all have :no-index: on them. Sphinx 8.0.2 let me use ":mod:`coverage`" to refer to the module. Upgrading to Sphinx 8.1.3 causes a warning:

/Users/ned/coverage/trunk/doc/api.rst:12: WARNING: py:mod reference target not found: coverage [ref.mod]

If I remove :no-index: from one of the directives, then the link is made correctly.

How to Reproduce

To reproduce, clone the coverage.py repo and run tox -e doc. Three commits of interest:

• 5369f8ad: Sphinx 8.0.2 with the docs building correctly
• 13a52255: Upgrade to Sphinx 8.1.3, generates a warning, no link created
• c179fb2f: Removed :no-index:, all builds properly.

Environment Information

Platform:              darwin; (macOS-14.7-arm64-arm-64bit)
Python version:        3.11.10 (main, Oct 20 2024, 13:53:59) [Clang 16.0.0 (clang-1600.0.26.3)])
Python implementation: CPython
Sphinx version:        8.1.3
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

No response

Additional context

No response

[AA-Turner]

I think that this is related to #12844, but I’m not able to check at the moment.

[electric-coder]

c179fb2f: Removed :no-index:, all builds properly.

I read the code containing .. module:: coverage and it's used once without :no-index: in api_module.rst and twice with :no-index: in api_coverage.rst and api_coveragedata.rst... There's no instance of .. automodule:: coverage (if there were it could also function as a reST module declaration, but there isn't).

If I remove :no-index: from one of the directives, then the link is made correctly.

This is expected behavior..! Those reST directives are declarations, so at least one of them has to be inserted into the index in order for the cross-reference :mod:`coverage` to have a valid target. I'm not sure if I'm following but I'm pretty certain that's always been the Sphinx behavior since at least Sphinx 5.

So if PR c179fb2f is building why not go with it? To me it seems to have correct reStructuredText syntax.

(btw, huge fan of coverage.py here 👍 )

[AA-Turner]

Using https://github.com/nedbat/coveragepy/commit/13a52255303676fdd05bebaeaf791d6a85f72e55:

Sphinx 7.3.7:

PS> uv pip install "sphinx~=7.3.0" -q
PS> sphinx-build --version
sphinx-build 7.3.7
PS> sphinx-build -b html -aEnqW doc doc/_build/html
** Prerelease = False

Warning, treated as error:
S:\Development\coveragepy\doc\api.rst:12:py:mod reference target not found: coverage

Sphinx 8.1.2:

PS> uv pip install "sphinx~=8.1.0" -q
PS> sphinx-build --version
sphinx-build 8.1.3
PS> sphinx-build -b html -aEnqW doc doc/_build/html
** Prerelease = False
S:\Development\coveragepy\doc\api.rst:12: WARNING: py:mod reference target not found: coverage [ref.mod]

So I am fairly confident that this is a (now solved) regression and will close this issue.

I also don't think that most of these .. module:: directives are needed, and have opened https://github.com/nedbat/coveragepy/pull/1882 in coverage.py.

Thanks @nedbat for reporting!

A