Sphinx Multiversion

0.2.4 · active · verified Thu Apr 16

sphinx-multiversion is a Sphinx extension that enables the creation of multiple versions of your project's documentation. It supports building documentation from different branches or tags in a Git repository, allowing users to easily switch between versions. The current version is 0.2.4. Releases are infrequent but stable, often coinciding with new Sphinx releases or major feature additions.

Common errors

```
ModuleNotFoundError: No module named 'sphinx_multiversion'
```
cause `sphinx-multiversion` is not installed in the environment or not added to `extensions` in `conf.py`.

fix `pip install sphinx-multiversion` and ensure `'sphinx_multiversion'` is in the `extensions` list in your `conf.py`.
```
WARNING: [smv] No branches matched 'smv_branch_whitelist' (or 'smv_tag_whitelist')
```
cause The regular expressions for `smv_branch_whitelist` or `smv_tag_whitelist` in `conf.py` do not match any existing branches or tags in your Git repository.

fix Adjust your `smv_branch_whitelist` or `smv_tag_whitelist` regex in `conf.py` to correctly capture the desired branches/tags, or verify that the branches/tags actually exist. E.g., `smv_branch_whitelist = r'^(main|master)$'`.
```
sphinx-multiversion: error: unrecognized arguments: . _build/html
```
cause This usually indicates an older version of `sphinx-multiversion` or incorrect command-line syntax. The arguments are meant for `sphinx-build` but not correctly parsed by `sphinx-multiversion`.

fix Ensure you are using the correct command-line syntax: `sphinx-multiversion <sourcedir> <outputdir> [OPTIONS]`. The common pattern is `sphinx-multiversion . _build/html`. Update `sphinx-multiversion` if it's an old version.
```
The 'sphinx-build' command was not found. Make sure you have Sphinx installed.
```
cause `sphinx-multiversion` internally calls `sphinx-build`. If Sphinx is not installed or not in your system's PATH, this error will occur.

fix Install Sphinx: `pip install Sphinx`.
```
jinja2.exceptions.TemplateNotFound: versions.html
```
cause `sphinx-multiversion` provides a `versions.html` template for its version switcher, but if your Sphinx theme overrides or doesn't correctly include the necessary Jinja2 environment, it might not find it. This can also happen with outdated `html_theme_path` or custom theme issues.

fix Ensure your theme is compatible with Sphinx extensions and correctly inherits or includes `sphinx_multiversion`'s templates. Check the theme's `layout.html` for a `{% include "versions.html" %}` or similar inclusion point. Consider temporarily switching to a default theme to isolate the problem.

Warnings

gotcha `conf.py` compatibility across versions. `sphinx-multiversion` runs a separate build for each version. Ensure your `conf.py` is compatible across all versions you want to build. Changes in newer branches won't automatically apply to old tags.
Fix: Design `conf.py` to be forward/backward compatible, or use conditional logic (e.g., `if 'v1.0.0' in os.environ.get('SMV_TAG', ''):`) to adapt settings for specific versions. Consider maintaining separate `conf.py` files for significantly different versions if necessary.
gotcha Performance issues with many versions or large repositories. Building documentation for a large number of branches/tags in a sizable repository can be resource-intensive and time-consuming, especially in CI/CD pipelines.
Fix: Use `smv_branch_whitelist` and `smv_tag_whitelist` aggressively to limit the number of versions built. Implement caching for Git operations in CI/CD, or consider dedicated build environments.
gotcha Output directory structure and version linking. Incorrect configuration of `smv_outputdir_format` or base URLs can lead to broken links or incorrect version switching in the generated HTML, especially when deployed to a web server.
Fix: Carefully configure `smv_outputdir_format` to match your deployment strategy. Ensure your web server is set up to correctly serve static files from the generated version directories, or rely on `sphinx-multiversion`'s own version switcher (usually works out-of-the-box).
gotcha Broken relative paths in documentation files when versions are nested. Hardcoding relative paths (e.g., `../_static/image.png`) in `.rst` or `.md` files might break when a document is built under a different version subdirectory (e.g., `/v1.0.0/my_doc.html` vs `/main/my_doc.html`).
Fix: Use Sphinx's standard `:doc:`, `:ref:`, and `|version|` variables where possible. For assets, use absolute paths from the root of the documentation project (e.g., `/_static/image.png`) if your web server configuration allows, or use Sphinx's `image` directive which handles paths correctly.
gotcha Compatibility issues with major Sphinx upgrades. `sphinx-multiversion` relies on Sphinx internals. Upgrading Sphinx to a major new version (e.g., 6.x to 7.x) without verifying `sphinx-multiversion` compatibility can lead to unexpected build failures.
Fix: Always test `sphinx-multiversion` with new major Sphinx versions in a test environment before deploying to production. Check `sphinx-multiversion` release notes for compatibility announcements.

Install

pip install sphinx-multiversion Install latest version

Imports

sphinx_multiversion
wrong:
```
import sphinx_multiversion
```
correct:
```
extensions = ['sphinx_multiversion', 'sphinx.ext.autodoc'] # in conf.py
```
`sphinx-multiversion` is a Sphinx extension. It is enabled by adding its name (`'sphinx_multiversion'`) to the `extensions` list in your `conf.py` file. It is not designed for direct Python import into application code.

Quickstart

To set up `sphinx-multiversion`, first add it to your `extensions` list in `conf.py`. Then, configure `smv_tag_whitelist` and `smv_branch_whitelist` with regular expressions to specify which Git tags and branches should have their documentation built. Finally, run the `sphinx-multiversion` command with your source and output directories.

# conf.py
import os

project = 'My Multi-version Project'
copyright = '2024, Your Name'
version = '0.1'
release = '0.1.0'

extensions = [
    'sphinx_multiversion',
    'sphinx.ext.autodoc',
]

# Multiversion configuration (adjust regex as needed)
# Builds documentation for tags matching vX.Y.Z
smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'
# Builds documentation for 'main' and 'develop' branches
smv_branch_whitelist = r'^(main|develop)$'
# Default remote to fetch from
smv_remote_whitelist = 'origin'

# To build:
# Run this command from your documentation root (where conf.py is located):
# sphinx-multiversion . _build/html

view raw JSON →