repomatic.docs module

Regenerate Sphinx API docs and dynamic documentation content.

Backs the update-docs command: orchestrates sphinx-apidoc, the RST-to-MyST conversion, the project’s docs/docs_update.py script, and the self-updating directive-block refresh. Configuration is read from [tool.repomatic.docs].

repomatic.docs.validate_docs_script_path(script, repo_root)[source]

Validate and resolve a docs update script path.

Parameters:

  • script (str) – Configured docs.update-script path, relative to the repo.

  • repo_root (Path) – Repository root the script path resolves against.

Return type:

Path | None

Returns:

The resolved path, or None when the configured value is empty.

Raises:

ClickException – If the path escapes the repository root or is not a .py file under docs/.

repomatic.docs.DIRECTIVE_BLOCK_MARKERS: tuple[str, ...] = ('{matrix}', '<!-- matrix', ':mirror:', '<!-- mirror')

Markers of a self-updating block click-extra refresh-directives rewrites.

Every form the refresh recognizes: the {matrix} MyST fence (live-rendered by Sphinx), the <!-- matrix --> comment region (whose embedded table renders on GitHub too), and the python:render :mirror: region (<!-- mirror -->, whose generator Python the refresh executes).

repomatic.docs.has_directive_block(path)[source]

Whether path carries a self-updating block worth refreshing.

Parameters:

path (Path) – Markdown file to scan.

Return type:

bool

Returns:

True when any DIRECTIVE_BLOCK_MARKERS entry appears.

repomatic.docs.update_docs(config, *, check=False)[source]

Regenerate Sphinx autodoc stubs and run the project’s update script.

Orchestrates four phases:

  1. Run sphinx-apidoc to generate RST stubs for all modules.

  2. If MyST-Parser is detected, convert the RST stubs to MyST markdown with {eval-rst} blocks.

  3. Run the project-specific docs/docs_update.py script (if present) to generate dynamic content.

  4. Refresh self-updating blocks ({matrix} compatibility tables and python:render :mirror: regions) found in docs/ pages and readme.md, via click-extra refresh-directives.

Parameters:

  • config (Config) – The resolved [tool.repomatic] configuration.

  • check (bool) – Report out-of-date content without writing, for CI drift detection. Phases 1–2 regenerate files and have no dry-run mode, so they are skipped; the self-updating phases run in their own check modes (docs_update.py --check and refresh-directives --check) and any drift raises a ClickException. The update script must accept a --check flag to participate: a script that ignores it will still write.

Return type:

None