[Darlokt]

Purpose

Hej, in #14675, I reported that parallel builds can generate an unreferenced module page.

Upon little bit further investigation, I found that the extra output is not caused by parallelization as I originally thought, but caused by sphinx.ext.viewcode.collect_pages() using every successful source-analysis entry as a module-page candidate and every cache key when generating the module overview and parent breadcrumbs.

A successful analysis entry can have an empty used mapping when viewcode finds and analyzes the source module but does not find a source tag for the documented object.
These entries can survive in both serial and parallel builds.
Unavailable modules are also cached as False entries.
Empty used entries can generate unreferenced module pages, while both states can incorrectly affect the module overview and parent breadcrumbs.

The fix filters the cache entries at page-collection time and generates output only for successfully analyzed modules with at least one used source tag.
The same filtered set is used for module pages, the module overview, progress reporting, and parent breadcrumbs.
Analysis caching, incremental purging, and parallel environment merging are unchanged.

The regression tests use the viewcode-find-source event to create a stable analyzed-but-unused module instead of tying the tests to viewcode's current handling of PEP 695 type aliases.
They cover fresh serial and parallel builds.
Collector coverage also checks an unavailable-module sentinel, a used child module, the overview, progress reporting, parent breadcrumbs, and preservation of the analysis cache.

References

• Closes sphinx.ext.viewcode generates a module page with no source links #14675

AI Disclosure

OpenAI Codex assisted with reproduction variants, and generation and review of portions of the implementation and regression tests. All AI-assisted changes were reviewed and understood by me.

[Darlokt]

With #14611, #14679, #14681 all the CI problems should be fixed.