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:

click.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.TOCTREE_ENTRY_RE = re.compile('^[ \\t]*(\\w+(?:\\.\\w+)+)\\s*$', re.MULTILINE)

A toctree entry of a generated index page: a dotted module name alone on its line.

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

repomatic.docs.wire_api_pages_into_toctrees(docs_dir)[source]

List every generated API page in the toctree of its parent index.

sphinx-apidoc --no-toc writes one page per module and no package index, so a module added after an index was last written stays orphaned: the page exists, nothing points at it, and Sphinx reports document isn't included in any toctree as a warning the build survives. Wiring it here is what keeps the roster whole without a hand edit per module, and it is the half click_extra.convert_rst_files_in_directory() cannot do, since that one only declines to overwrite an existing page.

A page goes under Subpackages when it documents a package: it is itself an index, or its title says so. It goes under Submodules otherwise. An index missing the section it needs is left alone and named in the return value, since inventing a heading would guess at a page layout this function does not own.

Parameters:

docs_dir (Path) – The docs/ directory holding the generated pages.

Return type:

list[str]

Returns:

One <page> -> <index> line per entry inserted, plus a <page>: <reason> line per page that could not be wired.

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, then list every page in the toctree of its parent index.

  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