tests.test_sphinx_crossrefs module

Render tests for Sphinx cross-references in the built documentation.

Build the docs once and assert against the real HTML that the generated summary tables deep-link to the sections they describe, that each changelog release is anchored on its version, and that intersphinx references to Click resolve to the upstream site. This catches drift the moment a {click:config} or {click:tree} directive stops wiring its anchors, or an intersphinx_mapping URL goes stale, neither of which a mock-based test would notice.

tests.test_sphinx_crossrefs.built_docs(tmp_path_factory: TempPathFactory) → Path

Build the HTML documentation once and return its output directory.

Builds into a throwaway directory (rather than docs/_build) so the run is hermetic and never clobbers a developer’s local build.

Return type:

Path

tests.test_sphinx_crossrefs.read_html(built_docs, filename)

Read a built HTML page.

Return type:

str

tests.test_sphinx_crossrefs.test_changelog_releases_are_anchored_on_their_version(built_docs, source, page)

Each release of the changelog has an anchor made from its version.

docutils reduces a release heading to nothing and numbers its section from a per-page counter, so #id40 names another release after each new one. ReleaseAnchors of docs/conf.py gives each section an anchor like #v7-17-1 instead.

tests.test_sphinx_crossrefs.test_summary_table_links_to_its_sections(built_docs, page, anchor)

Each generated summary table deep-links every row to its own section.

Both directives render a table of contents above the detail sections, so a row whose target never materialized leaves a dead link on the published page rather than failing the build.

tests.test_sphinx_crossrefs.test_intersphinx_click_resolves(built_docs)

Click cross-references resolve to the upstream documentation site.

Read from the module’s own page rather than the CLI guide: a Click link is emitted by a rendered signature or docstring, and the generated API reference lives only on the repomatic.* pages. The guide keeps the {click:tree} output, which links within this site and would pass this assertion for the wrong reason.

--separate gives each module its own page, so this names repomatic.cli.main rather than the repomatic.cli package page, which documents only the package’s __init__ and carries no signature.