tests.test_readme module

Tests for documentation sync with code.

tests.test_readme.IMAGE_SRC_RE = re.compile('<img[^>]*\\ssrc=["\']([^"\']+)["\']|!\\[[^\\]]*\\]\\(([^)\\s]+)')

Every image reference in a Markdown file, HTML tag or Markdown syntax.

tests.test_readme.test_readme_images_are_absolute()

Every image in readme.md must be an absolute URL.

pyproject.toml sets readme = "readme.md", so this file ships verbatim as the PyPI long description. GitHub resolves a relative path against the repository; PyPI has no such base and renders a broken image. The logo banner shipped relative and 404’d on every release page until 7.7.1.

Local paths stay correct on GitHub, which is what makes this invisible in review: the only place the breakage shows is the published project page.

Return type:

None

tests.test_readme.test_docs_cli_reference_uses_tree_directive()

docs/cli.md must render the CLI reference through {click:tree}.

The directive walks the live command tree at build time, so per-command coverage is guaranteed by construction. This canary only guards against the directive block being dropped from the page.

Return type:

None

tests.test_readme.test_docs_config_reference_uses_config_directive()

docs/configuration.md must render the reference through {click:config}.

The directive documents the live Config schema at build time, from the same schema_field_infos() records show-config renders, so option coverage is guaranteed by construction. This canary only guards against the directive block being dropped from the page.

Return type:

None

tests.test_readme.test_docs_bridge_table_covers_registry()

The tool-runner.md table must list every registry tool that supports translation.

A tool supports [tool.X] translation when it does not natively read pyproject.toml (reads_pyproject=False) and can receive a translated config via either a config_flag, a native_config_files target in a non-editorconfig format (editorconfig files are shared across tools and not suitable as single-tool bridge targets), or a FLAGS translation to CLI options (like Nuitka).

Return type:

None

tests.test_readme.test_docs_tip_table_covers_registry()

The tool-runner.md table must list every registry tool that natively reads pyproject.toml.

Tools with reads_pyproject=True in the registry should appear in the tool table with ‘Native’ support. The table may also list non-registry tools (like coverage.py, pytest, uv) that the workflows use and that natively read [tool.*] sections.

Return type:

None

tests.test_readme.test_docs_tool_runner_uses_render_blocks(renderer)

docs/tool-runner.md must render its registry content live.

Each repomatic.tooling.tool_registry renderer is embedded through a {python:render} block, so registry coverage is by construction. These canaries only guard against a block being dropped from the page.

Return type:

None

tests.test_readme.test_every_module_has_a_docs_automodule(module)

Every module has its own reference page, carrying its automodule.

[tool.repomatic] docs.apidoc-extra-args passes --separate, so the reference is one page per module rather than one page per package. That keeps a page’s length tied to the module it documents, and it is why this checks for a page named after the module rather than for an entry on a package page.

These pages are write-once: click_extra.convert_rst_files_in_directory() keeps an existing .md and discards the regenerated .rst, so a module added later silently goes undocumented (Sphinx then warns “document isn’t included in any toctree”). The update-docs drift test cannot catch it, since the generator never rewrites a page that already exists. To rebuild one, delete it and run repomatic update-docs.

Parameters:

module (str) – Dotted module name that must own a reference page.

Return type:

None