NAME

repomatic update-docs - Regenerate Sphinx API docs and dynamic content

SYNOPSIS

repomatic update-docs [OPTIONS]

DESCRIPTION

Regenerate the Sphinx API pages and the dynamic content of the docs.

Runs these phases in order, and stops at the first one that fails:

1. Run sphinx-apidoc to generate the RST stub of every module.
2. Convert the RST stubs to MyST Markdown, if the project uses MyST-Parser.
3. List every generated page in the toctree of its parent index page.
4. Run docs/docs_update.py (docs.update-script), if it exists.
5. Reformat with pyproject-fmt each pyproject.toml an earlier phase changed.
6. Refresh the {matrix} and :mirror: blocks of docs/ and readme.md.

With --check, only phases 4 and 6 run, in their own check modes: they report out-of-date content and write nothing. The update script must accept a --check flag to take part.

The phases read their settings from [tool.repomatic.docs].

OPTIONS

--check

Report out-of-date self-updating content and exit non-zero, without writing anything. For CI drift detection.

--help / -h

Show this message and exit.

ENVIRONMENT

UPDATE_DOCS_CHECK

Report out-of-date self-updating content and exit non-zero, without writing anything. For CI drift detection.

UPDATE_DOCS__CLICK_DEFAULT_HELP

Show this message and exit.

EXIT STATUS

0

Success.

1

A runtime error, an aborted prompt (Ctrl-D), or a declined confirmation.

2

A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.

130

Interrupted with Ctrl-C: the process ends by SIGINT, reported as 130.

AUTHORS

Kevin Deldycke