Builder APIs

class sphinx_ape.build.BuildMode(value)

An enumeration.

LATEST = 0

Build and then push to ‘latest/’

MERGE_TO_MAIN = 1

Build and then push to ‘stable/’

RELEASE = 2

Build and then push to ‘stable/’, ‘latest/’, and the version’s release tag folder

class sphinx_ape.build.DocumentationBuilder(mode: BuildMode | None = None, base_path: Path | None = None, name: str | None = None, pages_branch_name: str | None = None, toc_tree_spec: TOCTreeSpec | None = None)

Builds either “latest”, or “stable” / “release” documentation.

build()

Build the documentation.

Example

>>> builder = DocumentationBuilder(
...     mode=BuildMode.LATEST, base_path=Path.cwd(), name="sphinx-ape"
... )
>>> builder.build()

Raises:

ApeDocsBuildError – When building fails.

clean()

Clean build directories.

publish(repository: str | None = None, push: bool = True)

Publish the documentation to GitHub pages. Meant to be run in CI/CD on releases.

Parameters:

• repository (str | None) – The repository name. Defaults to GitHub env-var or extraction from setup file.

• push (bool) – Set to False to skip git add, commit, and push.

Raises:

ApeDocsPublishError – When publishing fails.