sphinx-polyversion

Build multiple versions of your sphinx docs and merge them into one website.

• Isolated builds using venv, virtualenv or poetry
• git support
• Build with sphinx-build or custom commands
• Access and modify all versioning data inside conf.py
• Concurrent builds
• Override build configuration from commandline easily
• Render templates to the root directory containing the docs for each version
• Build from local working tree easily while mocking version data
• Not a sphinx extension -> standalone tool
• Configuration in a python script
• Highly customizable and scriptable through OOP
• Implement subclasses in your configuration script to add support for other VCS, Project/dependency management tools, build tools and whatever you require
• IDE integration and autocompletion

Have a look at the roadmap to find out about upcoming features.

Installation

pip install sphinx-polyversion

poetry add --group docs sphinx-polyversion

Usage

Example

Setup your sphinx docs in docs/source/sphinx. Add a conf.py file with the following to set directory:

from sphinx_polyversion.api import load

load(globals())
# This adds the following to the global scope
# html_context = {
#     "revisions": [GitRef('main', ...), GitRef('v6.8.9', ...), ...],
#     "current": GitRef('v1.4.6', ...),
# }

# process the loaded version information as you wish
html_context["latest"] = max(html_context["revisions"]) # latest by date

# sphinx config
project = "foo"
# ...

Configure sphinx-polyversion in the file docs/poly.py.

from pathlib import Path

from sphinx_polyversion.api import apply_overrides
from sphinx_polyversion.driver import DefaultDriver
from sphinx_polyversion.git import Git, file_predicate
from sphinx_polyversion.pyvenv import Poetry
from sphinx_polyversion.sphinx import SphinxBuilder

#: Regex matching the branches to build docs for
BRANCH_REGEX = r".*"

#: Regex matching the tags to build docs for
TAG_REGEX = r".*"

#: Output dir relative to project root
OUTPUT_DIR = "docs/build"

#: Source directory
SOURCE_DIR = "docs/source"

#: Arguments to pass to `poetry install`
POETRY_ARGS = "--only sphinx --sync".split()

#: Arguments to pass to `sphinx-build`
SPHINX_ARGS = "-a -v".split()

#: Mock data used for building local version
MOCK_DATA = {
    "revisions": [
        GitRef("v1.8.0", "", "", GitRefType.TAG, datetime.fromtimestamp(0)),
        GitRef("v1.9.3", "", "", GitRefType.TAG, datetime.fromtimestamp(1)),
        GitRef("v1.10.5", "", "", GitRefType.TAG, datetime.fromtimestamp(2)),
        GitRef("master", "", "", GitRefType.BRANCH, datetime.fromtimestamp(3)),
        GitRef("dev", "", "", GitRefType.BRANCH, datetime.fromtimestamp(4)),
        GitRef("some-feature", "", "", GitRefType.BRANCH, datetime.fromtimestamp(5)),
    ],
    "current": GitRef("local", "", "", GitRefType.BRANCH, datetime.fromtimestamp(6)),
}
#: Whether to build using only local files and mock data
MOCK = False

#: Whether to run the builds in sequence or in parallel
SEQUENTIAL = False

# Load overrides read from commandline to global scope
apply_overrides(globals())
# Determine repository root directory
root = Git.root(Path(__file__).parent)

# Setup driver and run it
src = Path(SOURCE_DIR)
DefaultDriver(
    root,
    OUTPUT_DIR,
    vcs=Git(
        branch_regex=BRANCH_REGEX,
        tag_regex=TAG_REGEX,
        predicate=file_predicate([src]), # exclude refs without source dir
    ),
    builder=SphinxBuilder(src / "sphinx", args=SPHINX_ARGS),
    env=Poetry.factory(args=POETRY_ARGS),
    template_dir=root / src / "templates",
    static_dir=root / src / "static",
    mock=MOCK_DATA,
).run(MOCK, SEQUENTIAL)

Build your docs by running

$ sphinx-polyversion docs/poly.py

Commandline Options

usage: sphinx-polyversion [-h] [-o [OVERRIDE [OVERRIDE...]]] [-v] [-l] [--sequential] conf [out]

Build multiple versions of your sphinx docs and merge them into one site.

positional arguments:
  conf                  Polyversion config file to load. This must be a python file that can be evaluated.
  out                   Output directory to build the merged docs to.

optional arguments:
  -h, --help            show this help message and exit
  -o [OVERRIDE [OVERRIDE ...]], --override [OVERRIDE [OVERRIDE ...]]
                        Override config options. Pass them as `key=value` pairs.
  -v, --verbosity       Increase output verbosity (decreases minimum log level). The default log level is ERROR.
  -l, --local, --mock   Build the local version of your docs.
  --sequential          Build the revisions sequentially.

This is the beginning of the README. Read the rest at the original. Read the full README ↗