Frequently Asked Questions¶
Why another tool for versioning Sphinx docs?¶
While there are several sphinx extensions out there (e.g. sphinxcontrib-versioning or sphinx-versions) none of them seem to work correctly with recent sphinx versions (as of March 2020). Their code heavily relies on monkey-patching Sphinx internals at runtime, which is error-prone and makes the code a mess.
In contrast, the extension part of
sphinx-multiversion does not do any fancy patching, it just provides some HTML context variables.
How does it work?¶
Instead of running sphinx build, just run sphinx-multiversion from the root of your Git repository.
It reads your Sphinx
conf.py file from the currently checked out Git branch for configuration, then generates a list of versions from local or remote tags and branches.
This data is written to a JSON file - if you want to have a look what data will be generated, you can use the
Then it copies the data for each version into separate temporary directories, builds the documentation from each of them and writes the output to the output directory.
conf.py file from the currently checked out branch will be used to build old versions, so it’s not necessary to make changes old branches or tags to add support for
This also means that theme improvements, template changes, etc. will automatically be applied to old versions without needing to add commits.
What are the license terms of
sphinx-multiversion is licensed under the terms of the BSD 2-Clause license.