sphinx_polyversion.sphinx

Builder Implementations for running sphinx.

Classes

CommandBuilder(source, cmd[, encoder, ...])

A builder that starts another process.

Placeholder(value)

Placeholders that can be used in commands.

SphinxBuilder(source, *[, args, encoder, ...])

A CommandBuilder running sphinx-build.
class sphinx_polyversion.sphinx.CommandBuilder(source: str | PurePath, cmd: Iterable[str | Placeholder], encoder: json.JSONEncoder | None = None, pre_cmd: Iterable[str | Placeholder] | None = None, post_cmd: Iterable[str | Placeholder] | None = None)[source]

Bases: Builder[Environment, None]

A builder that starts another process.

This allows you to run any command for building your docs. You can use the placeholders from the Placeholder enum in the command provided. These placeholders will be replaced with their actual values before the subprocess is run.

Parameters:

  • source (PurePath) – The relative source location to pass to the command.

  • cmd (Iterable[str | Placeholder]) – The command to run.

  • encoder (json.JSONEncoder | None, optional) – The encoder to use for serializing the metadata, by default None

  • pre_cmd (Iterable[str | Placeholder], optional) – Additional command to run before cmd.

  • post_cmd (Iterable[str | Placeholder], optional) – Additional command to run after cmd.

async build(environment: Environment, output_dir: Path, data: None | bool | int | float | str | List[JSONable] | Tuple[JSONable, ...] | Dict[None | bool | int | float | str, JSONable] | Transformable) → None

Build and render a documentation.

This method runs the command the instance was created with. The metadata will be passed to the subprocess encoded as json using the POLYVERSION_DATA environment variable.

Parameters:

  • environment (Environment) – The environment to use for building.

  • output_dir (Path) – The output directory to build to.

  • data (JSONable) – The metadata to use for building.

class sphinx_polyversion.sphinx.Placeholder(value)[source]

Bases: Enum

Placeholders that can be used in commands.

OUTPUT_DIR = 2

represents the output location to render the docs to

SOURCE_DIR = 1

represents the location of the source files to render the docs from

class sphinx_polyversion.sphinx.SphinxBuilder(source: str | PurePath, *, args: Iterable[str] = [], encoder: json.JSONEncoder | None = None, pre_cmd: Iterable[str | Placeholder] | None = None, post_cmd: Iterable[str | Placeholder] | None = None)[source]

Bases: CommandBuilder

A CommandBuilder running sphinx-build.

Parameters:

  • source (PurePath) – The relative source location to pass to the command.

  • args (Iterable[str], optional) – The arguments to pass to sphinx-build, by default []

  • encoder (json.JSONEncoder | None, optional) – The encoder to use for serializing the metadata, by default None

  • pre_cmd (Iterable[str | Placeholder], optional) – Additional command to run before cmd.

  • post_cmd (Iterable[str | Placeholder], optional) – Additional command to run after cmd.