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-directivesrewrites.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 thepython:render:mirror:region (<!-- mirror -->, whose generator Python the refresh executes).
- repomatic.docs.TOCTREE_ENTRY_RE = re.compile('^[ \\t]*(\\w+(?:\\.\\w+)+)\\s*$', re.MULTILINE)ΒΆ
A
toctreeentry of a generated index page: a dotted module name alone on its line.The reST directive that
click_extrawraps 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:
EnumOne 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.
- class repomatic.docs.PhaseStatus(*values)[source]ΒΆ
Bases:
EnumHow one phase of
update-docsended.- 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:
objectWhat one phase of
update-docsdid.- status: PhaseStatusΒΆ
How it ended.
- repomatic.docs.validate_docs_script_path(script, repo_root)[source]ΒΆ
Validate and resolve a docs update script path.
- Parameters:
- Return type:
- Returns:
The resolved path, or
Nonewhen the configured value is empty.- Raises:
ValueError β If the path escapes the repository root or is not a
.pyfile underdocs/.
- 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:
- Returns:
Truewhen anyDIRECTIVE_BLOCK_MARKERSentry appears.
- repomatic.docs.wire_api_pages_into_toctrees(docs_dir)[source]ΒΆ
List every generated API page in the
toctreeof its parent index.sphinx-apidoc --no-tocwrites 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 reportsdocument isn't included in any toctreeas a warning the build survives. Wiring it here is what keeps the roster whole without a hand edit per module, and it is the halfclick_extra.convert_rst_files_in_directory()cannot do, since that one only declines to overwrite an existing page.A page goes under
Subpackageswhen it documents a package: it is itself an index, or its title says so. It goes underSubmodulesotherwise. 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.
- repomatic.docs.update_docs(config, *, check=False)[source]ΒΆ
Run the phases of
DocsPhasein 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 whoseDocsPhase.checksis true run, in their own check modes (docs_update.py --checkandrefresh-directives --check). The update script must accept a--checkflag to participate: a script that ignores it will still write.
- Return type:
- Returns:
One result per phase that ran.
- Raises:
ValueError β When
docs.update-scriptnames a path outsidedocs/, or a file that is not Python.