tests.test_docs module

Tests for the update-docs orchestration and this repository’s docs wiring.

tests.test_docs.test_docs_group_carries_the_test_group()

The Sphinx environment imports the test suite it documents.

autodoc imports every module it renders a page for, docs/tests.md documents each test module, and each of those imports pytest. Without the test group, all of them fail to import and their pages publish empty. The build reports that as a warning, so nothing else catches it.

Return type:

None

tests.test_docs.test_validate_docs_script_path_empty_returns_none(tmp_path)

An empty configured path disables the script phase.

tests.test_docs.test_validate_docs_script_path_valid(tmp_path)

A .py file under docs/ resolves to its absolute path.

tests.test_docs.test_validate_docs_script_path_rejects(tmp_path, script, match)

Paths outside docs/, outside the repo, or non-.py are rejected.

tests.test_docs.test_run_docs_tool_builds_frozen_docs_group_command()

The command runs the tool through a frozen uv with the docs group.

tests.test_docs.test_run_docs_tool_raises_on_failure()

A non-zero exit code raises a ClickException naming the phase.

tests.test_docs.test_update_docs_noop_without_sphinx(tmp_path, monkeypatch)

A project with no Sphinx configuration runs no docs tooling.

tests.test_docs.test_update_docs_runs_apidoc_for_autodoc_project(tmp_path, monkeypatch)

An autodoc-enabled Sphinx project regenerates its apidoc stubs.

tests.test_docs.test_update_docs_skips_apidoc_without_active_autodoc(tmp_path, monkeypatch)

Without an active autodoc extension, no docs tooling runs.

tests.test_docs.test_update_docs_check_skips_writes_and_propagates(tmp_path, monkeypatch)

check=True skips the write phases and runs the rest in check mode.

tests.test_docs.test_update_docs_check_raises_on_drift(tmp_path, monkeypatch)

A non-zero exit from a check phase raises with an “out of date” message.

tests.test_docs.test_wire_api_pages_inserts_a_missing_entry(tmp_path)

A generated page absent from its parent toctree is listed, in order.

sphinx-apidoc --no-toc writes the page and no index entry, so a module added after the index was last written builds while Sphinx only warns document isn't included in any toctree. meta-package-manager hit this when tests.test_sbom_base landed: its page shipped orphaned and the conformance test guarding the roster turned every cell of its test matrix red.

tests.test_docs.test_wire_api_pages_is_idempotent(tmp_path)

A second pass over a wired tree rewrites nothing.

tests.test_docs.test_wire_api_pages_sorts_a_subpackage_into_its_own_toctree(tmp_path)

An index page joins Subpackages, a plain module joins Submodules.

tests.test_docs.test_wire_api_pages_reports_an_index_missing_its_section(tmp_path)

A page is left alone, and named, when its index carries no such toctree.

tests.test_docs.test_wire_api_pages_reads_a_myst_toctree_fence(tmp_path)

A page listed in a native MyST toctree fence counts as wired.

The fence holds its entries at the margin, where the reST directive that click_extra wraps in an {eval-rst} block indents them.

tests.test_docs.test_wire_api_pages_lists_a_package_without_submodule_pages(tmp_path)

A package page joins Subpackages even with no page below it.

Without --separate, sphinx-apidoc writes the modules of a package inline, so its title is all that tells a package page from a module page.