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.
pip install sphinx-multiversionVerified import paths — ran on the pinned version, not inferred.
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.
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.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.
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).
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.
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.