mafw.devtools.toolchain.tools.sphinx

Concrete ProjectTool implementation for Sphinx.

Sphinx is a project tool whose version lower bound is declared in project.optional-dependencies.doc. This module manages the >= specifier for Sphinx and validates updates by running the documentation build via hatch.

Update logic (inherited from ProjectTool):

  1. Query PyPI for the latest stable Sphinx release.

  2. Compare against the current lower bound in pyproject.toml.

  3. If a newer version exists, update the >= specifier.

Post-update validation (overridden here):

  1. Determine the highest supported Python version dynamically.

  2. Recreate the dev.py<version> hatch environment to force fresh dependency resolution.

  3. Run hatch run dev.py<version>:doc to build the documentation.

  4. If the build fails, revert pyproject.toml to its previous content.

The revert pattern uses _revert() which restores the raw pyproject.toml content saved before the update.

Classes

SphinxTool([project_root])

Manage Sphinx's version lower bound in pyproject.toml.
class mafw.devtools.toolchain.tools.sphinx.SphinxTool(project_root: Path | None = None)[source]

Bases: ProjectTool

Manage Sphinx’s version lower bound in pyproject.toml.

Sphinx is categorized as a project tool because its version is controlled through the doc optional-dependencies group in pyproject.toml. After an update, the doc hatch environment is recreated and the documentation build is executed to validate compatibility. If the build fails, pyproject.toml is reverted to its pre-update state.

All standard behaviour (version detection, update, verify, bootstrap) is provided by ProjectTool. Only post_update() is overridden to run the documentation build.

Parameters:

project_root (Path | None) – Path to the project root directory containing pyproject.toml. Defaults to the current working directory.

post_update() → None[source]

Recreate the doc environment and run the documentation build.

Forces recreation of the doc hatch environment to ensure the newly specified dependency versions are resolved and installed. Then executes hatch run dev.py3.14:doc from the project root.

If the documentation build fails (non-zero exit code), the pyproject.toml is reverted to its saved pre-update content and a DevtoolsError is raised. The error message includes the conflicting package name when the failure is caused by a dependency resolution conflict.

Raises:

DevtoolsError – If environment recreation or the documentation build fails after the update.

property env_name: str

Hatch environment where sphinx documentation is built.

Returns:

"dev"

Return type:

str

property package_name: str

PyPI package name for Sphinx.

Returns:

"sphinx"

Return type:

str

property section_path: str

Dot-separated TOML path to the dependency array containing Sphinx.

Returns:

"project.optional-dependencies.doc"

Return type:

str