repomatic.docs moduleΒΆ

Regenerate Sphinx API docs and dynamic documentation content.

Backs the update-docs command, which runs the phases of DocsPhase in order: sphinx-apidoc, the RST-to-MyST conversion, the toctree wiring, the project’s docs/docs_update.py script, the reformat of a pyproject.toml that script changed, and the self-updating directive-block refresh. update_docs() returns one PhaseResult per phase it ran, and the command reports them. Configuration is read from [tool.repomatic.docs].

repomatic.docs.DIRECTIVE_BLOCK_MARKERS: tuple[str, ...] = ('{matrix}', '<!-- matrix', '<!-- envelope', ':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), the <!-- envelope --> region listing the obsolete bounds of the support envelope, and the python:render :mirror: region (<!-- mirror -->, whose generator Python the refresh executes).

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.

class repomatic.docs.DocsPhase(*values)[source]ΒΆ

Bases: Enum

One phase of update-docs, in the order the phases run.

The help of the command lists the phases from this registry, so the two cannot drift apart.

APIDOC = ('sphinx-apidoc', 'Run sphinx-apidoc to generate the RST stub of every module.')ΒΆ
CONVERSION = ('RST conversion', 'Convert the RST stubs to MyST Markdown, if the project uses MyST-Parser.')ΒΆ
TOCTREE = ('Toctree wiring', 'List every generated page in the toctree of its parent index page.')ΒΆ
SCRIPT = ('Docs update script', 'Run docs/docs_update.py (docs.update-script), if it exists.')ΒΆ
PYPROJECT = ('pyproject.toml reformat', 'Reformat with pyproject-fmt each pyproject.toml an earlier phase changed.')ΒΆ
DIRECTIVES = ('Directive-block refresh', 'Refresh the {matrix}, <!-- envelope --> and :mirror: blocks of docs/ and readme.md.')ΒΆ
labelΒΆ

Short name of the phase, for a report line.

descriptionΒΆ

What the phase does, in the plain text of the command’s help.

property checks: boolΒΆ

Whether the phase has a check mode, so update-docs --check runs it.

The other phases write files and have no dry-run mode.

class repomatic.docs.PhaseStatus(*values)[source]ΒΆ

Bases: Enum

How one phase of update-docs ended.

DONE = 1ΒΆ

The phase ran, and wrote or found everything up to date.

SKIPPED = 2ΒΆ

The phase has nothing to do in this project.

DRIFT = 3ΒΆ

In check mode, the phase found out-of-date content.

FAILED = 4ΒΆ

The phase failed, which stops the phases after it.

class repomatic.docs.PhaseResult(phase, status, message='')[source]ΒΆ

Bases: object

What one phase of update-docs did.

phase: DocsPhaseΒΆ

The phase that ran.

status: PhaseStatusΒΆ

How it ended.

message: str = ''ΒΆ

What to tell the user: the work done, the reason for a skip, the out-of-date content, or the failure.

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:

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

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.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]ΒΆ

Run the phases of DocsPhase in order, and say how each ended.

A failed phase stops the phases after it. A project with no Sphinx configuration runs no phase.

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

  • check (bool) – Report out-of-date content without writing, for CI drift detection. Only the phases whose DocsPhase.checks is true run, in their own check modes (docs_update.py --check and refresh-directives --check). The update script must accept a --check flag to participate: a script that ignores it will still write.

Return type:

list[PhaseResult]

Returns:

One result per phase that ran.

Raises:

ValueError – When docs.update-script names a path outside docs/, or a file that is not Python.