sphinx_polyversion.driver

The core logic of this tool and orchestrator of everything.

Classes

`DefaultDriver`(root, output_dir, *, vcs, ...)	Simple driver implementation.
`Driver`(root, output_dir, *[, mock])	Base driver class.

class sphinx_polyversion.driver.DefaultDriver(root: StrPath, output_dir: StrPath, *, vcs: VersionProvider[JRT], builder: Builder[ENV, Any] | Mapping[S, Builder[ENV, Any]], env: Callable[[Path, str], ENV] | Mapping[S, Callable[[Path, str], ENV]], namer: Callable[[JRT], str] | None = None, selector: Callable[[JRT, Iterable[S]], S | Coroutine[Any, Any, S]] | None = None, data_factory: Callable[[DefaultDriver[JRT, ENV, S], JRT, ENV], JSONable] | Mapping[S, Callable[[DefaultDriver[JRT, ENV, S], JRT, ENV], JSONable]] | None = None, root_data_factory: Callable[[DefaultDriver[JRT, ENV, S]], dict[str, Any]] | None = None, encoder: Encoder | None = None, static_dir: StrPath | None = None, template_dir: StrPath | None = None, mock: MockData | None = None)[source]

Bases: Driver[JRT, ENV], Generic[JRT, ENV, S]

Simple driver implementation.

This convenience class allows creating a driver from a version provider, a builder and an Environment factory.

You can provide a dict for env, data_factory or builder that maps revisions to builders. In that case you must also provide a selector that is used to determine the closest key in the dict for the revision to build. This key is then used to get the builder or environment factory from the dict provided.

Parameters:

cwd (Path) – The current working directory
output_dir (Path) – The directory where to place the built docs.
vcs (VersionProvider[JRT]) – The version provider to use.
builder (Builder[ENV, Any]) – The builder to use.
env (Callable[[Path, str], ENV]) – A factory producing the environments to use.
data_factory (Callable[[DefaultDriver[JRT, ENV, S], JRT, ENV], JSONable], optional) – A callable returning the data to pass to the builder.
root_data_factory (Callable[[DefaultDriver[JRT, ENV, S]], dict[str, Any]], optional) – A callable returning the variables to pass to the jinja templates.
namer (Callable[[RT], str], optional) – A callable determining the name of a revision.
selector (Callable[[JRT, Iterable[S]], S | Coroutine[Any, Any, S]], optional) – The selector to use when either env or builder are a dict.
encoder (Encoder, optional) – The encoder to use for dumping versions.json to the output dir.
static_dir (Path, optional) – The source directory for root level static files.
template_dir (Path, optional) – The source directory for root level templates.
mock (MockData[RT] | None | Literal[False], optional) – Only build from local files and mock building all docs using the data provided.

build_failed(rev: JRT, exc_info: Tuple[Type[BaseException], BaseException, TracebackType]) → None

Handle a failed build.

This logs the error.

Parameters:

rev (Any) – The revision that failed to build.
exc_info (EXC_INFO) – The exception raised by the build steps.

async build_root() → None

Build the root directory.

The root of the output directory contains subdirectories for the docs of each revision. This method adds more to this root directory.

builds: List[RT]: Revisions of successful builds.

async init_builder(rev: JRT) → Builder[ENV, Any]

Get the builder for a specific revision.

A different builder may be returned for each revision but the same builder can be used for multiple revisions as well.

Parameters:: rev (Any) – The revision the builder will be used for.
Return type:: Builder

Get the serializable metadata object for a revision.

This bundles a list of all revisions and a the current revision into a dictionary:

..code:

{"revisions": (*TARGETS), "current": REV}

Parameters:

rev (Any) – The revision the metadata should be bundled for.
env (Environment) – The environment for the given revision.

Returns:

The metadata to pass to the builder.

Return type:

JSONable

async init_environment(path: Path, rev: JRT) → ENV

Initialize the build environment for a revision and path.

The environment will be used to build the given revision and the path specifies the location where the revision is checked out.

Parameters:

path (Path) – The location of the revisions files.
rev (Any) – The revision the environment is used for.

Return type:

Environment

async init_vcs() → VersionProvider[JRT]: Prepare the building.

name_for_rev(rev: JRT) → str

Determine the name of a revision.

Parameters:: rev (Any) – The revision
Returns:: The name
Return type:: str

output_dir: Path: Directory for the built docs.

targets: Iterable[RT]: Revisions targeted to be build.

tmp_dir(rev: JRT) → AsyncGenerator[Path, None]

Create a temporary directory for a revision.

This directory is used to check the files of the revision out and for building. The context manager returned by this method should in turn return the path of the temporary directory created.

This implementation creates a temporary directory using tempfile.

Parameters:: rev (Any) – The revision to be build in the directory.
Returns:: A context manager creating and cleaning up the temp dir.
Return type:: AsyncContextManager[Path]

vcs: VersionProvider[RT]: The version provider used by the driver e.g. to determine build targets.

class sphinx_polyversion.driver.Driver(root: Path, output_dir: Path, *, mock: MockData | None = None)[source]

Bases: Generic[RT, ENV]

Base driver class.

The driver orchestrates all operations and provides the core logic. The default implementation is DefaultDriver.

Parameters:

cwd (Path) – The current working directory
output_dir (Path) – The directory where to place the built docs.
mock (MockData[RT] | None | Literal[False], optional) – Only build from local files and mock building all docs using the data provided.

run(): Build all revisions.

async arun() → None: Build all revisions (async).

abstract build_failed(rev: RT, exc_info: Tuple[Type[BaseException], BaseException, TracebackType]) → None

Handle a failed build.

This is a hook for a build fail.

Parameters:

rev (Any) – The revision that failed to build.
exc_info (EXC_INFO) – The exception raised by the build steps.

async build_local() → None

Build the local version only.

Raises:: ValueError – self.mock isn’t set.

async build_revision(rev: RT) → None

Build a revision.

This does all the work of creating a temporary directory, copying the files of the given revision to that directory, creating an Environment and calling the Builder.

Parameters:: rev (Any) – The revision to build.

abstract async build_root() → None

Build the root directory.

The root of the output directory contains subdirectories for the docs of each revision. This method adds more to this root directory.

build_succeeded(rev: RT, data: Any) → None

Handle a successful build.

This is a hook for a build success. This appends the revision to builds.

Parameters:

rev (Any) – The revision that was build.
data (Any) – The data returned by the builder.

builds: List[RT]: Revisions of successful builds.

async init() → None: Prepare the building.

abstract async init_builder(rev: RT) → Builder[ENV, Any]

Get the builder for a specific revision.

A different builder may be returned for each revision but the same builder can be used for multiple revisions as well.

Parameters:: rev (Any) – The revision the builder will be used for.
Return type:: Builder

Get the serializable metadata object for a revision.

Parameters:

rev (Any) – The revision the metadata should be bundled for.
env (Environment) – The environment for the given revision.

Returns:

The metadata to pass to the builder.

Return type:

JSONable

abstract async init_environment(path: Path, rev: RT) → ENV

Initialize the build environment for a revision and path.

The environment will be used to build the given revision and the path specifies the location where the revision is checked out.

Parameters:

path (Path) – The location of the revisions files.
rev (Any) – The revision the environment is used for.

Return type:

Environment

abstract async init_vcs() → VersionProvider[RT]

Return a version provider.

The returned instance will be used by the driver to determine the revisions to build.

Return type:: VersionProvider

abstract name_for_rev(rev: RT) → str

Determine the name of a revision.

Parameters:: rev (Any) – The revision
Returns:: The name
Return type:: str

output_dir: Path: Directory for the built docs.

run(mock: bool = False, sequential: bool = False) → None

Build all revisions or build from local files.

Parameters:

mock (bool, optional, default: False) – Whether to build all revisions (False) or from local files (True)
sequential (bool, optional, default: False) – Whether to build revisions in parallel (False) or sequential (True)

async srun() → None: Build all revisions (sequential).

targets: Iterable[RT]: Revisions targeted to be build.

abstract tmp_dir(rev: RT) → AsyncContextManager[Path]

Create a temporary directory for a revision.

This directory is used to check the files of the revision out and for building. The context manager returned by this method should in turn return the path of the temporary directory created.

Parameters:: rev (Any) – The revision to be build in the directory.
Returns:: A context manager creating and cleaning up the temp dir.
Return type:: AsyncContextManager[Path]

vcs: VersionProvider[RT]: The version provider used by the driver e.g. to determine build targets.