sphinx_polyversion.setuptools_scm

Setuptools SCM integration for sphinx-polyversion.

Functions

version_for_ref(repo_path, ref)

Get version that setuptools_scm determined for a given revision.

Classes

SetuptoolsScmDriver(root, output_dir, *, ...)

Driver that uses setuptools-scm to determine the version of each revision.
class sphinx_polyversion.setuptools_scm.SetuptoolsScmDriver(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: DefaultDriver[RT, ENV, S]

Driver that uses setuptools-scm to determine the version of each revision.

This driver requires that the project uses setuptools-scm and has a pyproject.toml file in the root of the repository.

Note

Must be used with GitRef (thus git vcs) and subclasses of VirtualPythonEnvironment

Note

Doesn’t work for legacy python projects that do not use a pyproject.toml file.

Parameters:

  • cwd (Path) – The current working directory

  • output_dir (Path) – The directory where to place the built docs.

  • vcs (VersionProvider[RT]) – 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[RT, ENV, S], RT, ENV], JSONable], optional) – A callable returning the data to pass to the builder.

  • root_data_factory (Callable[[DefaultDriver[RT, 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[[RT, 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.

builds: List[RT]

Revisions of successful builds.

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.

This implementation calls setuptools-scm to determine the version for the given revision and sets the environment variable SETUPTOOLS_SCM_PRETEND_VERSION_FOR_<DIST_NAME> in the returned environment.

Parameters:

  • path (Path) – The location of the revisions files.

  • rev (GitRef) – The revision the environment is used for.

Return type:

VirtualPythonEnvironment

output_dir: Path

Directory for the built docs.

targets: Iterable[RT]

Revisions targeted to be build.

vcs: VersionProvider[RT]

The version provider used by the driver e.g. to determine build targets.

async sphinx_polyversion.setuptools_scm.version_for_ref(repo_path: str | Path, ref: str) → Tuple[str, str] | None[source]

Get version that setuptools_scm determined for a given revision.

Calls setuptools-scm using the configuration in the pyproject.toml file. Alters the git describe command configured by appending the given :paramref:`ref`.

Warning

Only works when using git vcs.

Warning

Doesn’t work for legacy python projects that do not use a pyproject.toml file.

Parameters:

  • repo_path (str | Path) – The location of the git repository.

  • ref (str) – The reference of the revision.

Returns:

The version determined by setuptools-scm and the canonical distribution name, optional

Return type:

Tuple[str, str] | None

Raises:

FileNotFoundError – No pyproject.toml file was found in the repo.