API documentation

Entry application

The entry point for the package sphinx-versioned-docs is through sphinx_versioned.__main__.main(). The function is actually a Typer CLI with the various command-line options available.

sphinx_versioned.__main__.main(chdir: str = <typer.models.OptionInfo object>, output_dir: str = <typer.models.OptionInfo object>, git_root: str = <typer.models.OptionInfo object>, local_conf: str = <typer.models.OptionInfo object>, reset_intersphinx_mapping: bool = <typer.models.OptionInfo object>, sphinx_compatibility: bool = <typer.models.OptionInfo object>, prebuild: bool = <typer.models.OptionInfo object>, branches: str = <typer.models.OptionInfo object>, main_branch: str = <typer.models.OptionInfo object>, floating_badge: bool = <typer.models.OptionInfo object>, quite: bool = <typer.models.OptionInfo object>, verbose: bool = <typer.models.OptionInfo object>, loglevel: str = <typer.models.OptionInfo object>, force_branches: bool = <typer.models.OptionInfo object>) → None[source]

Typer application for initializing the sphinx-versioned build.

Parameters:

  • chdir (str) – Make this the current working directory before running. [Default = None]

  • output_dir (str) – Output directory. [Default = ‘docs/_build’]

  • git_root (str) – Path to directory in the local repo. Default is CWD.

  • local_conf (str) – Path to conf.py for sphinx-versions to read config from.

  • reset_intersphinx_mapping (bool) – Reset intersphinx mapping; acts as a patch for issue #17

  • sphinx_compatibility (bool) – Adds compatibility for older sphinx versions by monkey patching certain functions.

  • prebuild (bool) – Pre-builds the documentations; Use –no-prebuild to half the runtime. [Default = True]

  • branches (str) – Build docs for specific branches and tags. [Default = None]

  • main_branch (str) – Main branch to which the top-level index.html redirects to. [Default = ‘main’]

  • floating_badge (bool) – Turns the version selector menu into a floating badge. [Default = False]

  • quite (bool) – Quite output from sphinx. Use –no-quite to get output from sphinx. [Default = True]

  • verbose (bool) – Passed directly to sphinx. Specify more than once for more logging in sphinx. [Default = False]

  • loglevel (str) – Provide logging level. Example –log debug, [Default=’info’]

  • force_branches (str) – Force branch selection. Use this option to build detached head/commits. [Default = False]

Return type:

sphinx_versioned.build.VersionedDocs

Building workflow

class sphinx_versioned.build.VersionedDocs(config: dict, debug: bool = False)[source]

Bases: object

Handles main build workflow.

Chronologically, the __init__() first parses the config (input parameters via a dict) and then handles various paths, like current workding directory, source directory and output directory. Further, it selects the branches to pre-build/build then finally generates the top-level index.html file.

Parameters:

config (dict)

_build(tag, _prebuild: bool = False) → bool[source]

Internal build method which actually carries out the pre-build/build transctions inside a temporary directory then copy the asset files to the output directory if it’s not a pre-build.

Parameters:

  • tag (git.Branch or git.Tag) – Branch/tag to build.

  • _prebuild (bool) – Variable to perform/skip pre-builds for selected/all versions.

Return type:

bool

_generate_top_level_index() → None[source]

Generate a top-level index.html which redirects to the main-branch version specified via main_branch.

_handle_paths() → None[source]

Method to handle cwd and path for local config, as well as, configure GitVersions and the output directory.

build() → None[source]

Build workflow.

Method to build the branch in a temporary directory with the modified sphinx_versioned.lib.ConfigInject and injectes the versions flyout menu to the footer or the sidebars.

The method carries out the transaction via the internal build method _build().

prebuild() → None[source]

Pre-build workflow.

Method to pre-build the selected/all branches in a temporary environment. Essentially, it builds the various selected/all branches with the vanilla sphinx-build method and pass-on the branches which ends up successful in vanilla sphinx-build.

The method carries out the transaction via the internal build method _build().

Sphinx extension

The sphinx-extension is added by default on running sphinx-versioned to inject the versions flyout menu directly to the html files.

Interface with Sphinx.

class sphinx_versioned.sphinx_.EventHandlers[source]

Bases: object

Holds Sphinx event handlers as static or class methods.

Parameters:

  • CURRENT_VERSION (str) – Current version being built.

  • VERSIONS (sphinx_versioned.versions.BuiltVersions) – Pass through versions for them to be linked to be linked in the badge.

  • ASSETS_TO_COPY (list) – Assest to copy to output directory.

  • RESET_INTERSPHINX_MAPPING (bool) – Reset intersphinx mapping after each build.

  • FLYOUT_FLOATING_BADGE (bool) – Turns the version selector menu into a floating badge.

classmethod builder_finished_tasks(app, exc) → None[source]

Method to execute tasks after the sphinx builder is finished.

Parameters:
classmethod builder_inited(app) → None[source]

Update the Sphinx builder.

Parameters:

app (sphinx.application.Sphinx) – Sphinx application object.

classmethod html_page_context(app, pagename, templatename, context, doctree) → None[source]

Update the Jinja2 HTML context, exposes the Versions class instance to it.

Parameters:

  • app (sphinx.application.Sphinx) – Sphinx application object.

  • pagename (str) – Name of the page being rendered (without .html or any file extension).

  • templatename (str) – Page name with .html.

  • context (dict) – Jinja2 HTML context.

  • doctree (docutils.nodes.document) – Tree of docutils nodes.

sphinx_versioned.sphinx_.setup(app) → dict[source]

Called by Sphinx during phase 0 (initialization).

Parameters:

app (sphinx.application.Sphinx) – Sphinx application object.

Returns:

extension version

Return type:

dict

Utiliies/ Libraries

class sphinx_versioned.versions.BuiltVersions(versions: list, build_directory: str)[source]

Bases: _BranchTag

Handles versions to build. Builds upon the abstract base class sphinx_versioned.versions._BranchTag.

Parameters:

  • versions (list) – Versions to be build.

  • build_directory (str) – Path of the build directory.

_parse() → bool[source]

Parse raw branches/tags in GitVersions instance into separate variables.

class sphinx_versioned.versions.GitVersions(git_root: str, build_directory: str, force_branches: bool)[source]

Bases: _BranchTag

Handles git branches and tags. Builds upon the abstract base class sphinx_versioned.versions._BranchTag.

Initlizes and latches into the git repo.

Parameters:

  • git_root (str) – Git repository root directory.

  • build_directory (str) – Path of build directory.

  • force_branches (bool) – This option allows GitVersions to treat the detached commits as normal branches. Use this option to build docs for detached head/commits.

_parse_branches() → bool[source]

Parse branches and tags into separate variables.

Collect all branches and tags in GitVersions.all_versions. Additionally, if the head is detached and –force is supplied, then append a PseudoBranch representing the detached commit sha.

Return type:

bool

property active_branch

Property to get the currently active branch.

checkout(name, *args, **kwargs) → bool[source]

git checkout the branch/tag with its name.

Parameters:

name (str) – Name of the branch/tag.

class sphinx_versioned.versions.PseudoBranch(name: str)[source]

Bases: object

Class to generate a branch/pseudo-branch for git detached head/commit.

Parameters:

name (str) – Branch/pseudo-branch name.

class sphinx_versioned.versions._BranchTag[source]

Bases: ABC

Abstract base class for getting relative paths of branches and tags as properties.

property branches: dict

Get the branches and its index.html location.

Return type:

dict

property tags: dict

Get the tags and its index.html location.

Return type:

dict

Common objects used throughout the project.

class sphinx_versioned.lib.ConfigInject(*args)[source]

Bases: Config

Inject this extension into self.extensions. Append after user’s extensions.

exception sphinx_versioned.lib.HandledError[source]

Bases: Exception

Abort the program.

show(**_)[source]

Error messages should be logged before raising this exception.

class sphinx_versioned.lib.TempDir(defer_atexit=False)[source]

Bases: object

Similar to TemporaryDirectory in Python 3.x but with tuned weakref implementation.

Parameters:

defer_atexit (bool) – cleanup() to atexit instead of after garbage collection.

cleanup()[source]

Recursively delete directory.

sphinx_versioned.lib.mp_sphinx_compatibility() → bool[source]

Monkeypatches sphinx.application.Sphinx.add_stylesheet() -> sphinx.application.Sphinx.add_css_file() to add compatibility for versions using older sphinx

sphinx_versioned.lib.parse_branch_selection(branches: str) → tuple[source]

Parse the CLI-argument string to either select the branch/tag or exclude it.

Returns (None, None), if the input is None.

Parameters:

branches (str) – Input CLI-argument.

Returns:

select_branches, exclude_branches

Return type:

list, list