{"id":9322,"library":"sphinx-multiversion","title":"Sphinx Multiversion","description":"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.","status":"active","version":"0.2.4","language":"en","source_language":"en","source_url":"https://github.com/mr-zero-o/sphinx-multiversion","tags":["sphinx","documentation","versioning","git","extension"],"install":[{"cmd":"pip install sphinx-multiversion","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency as `sphinx-multiversion` is a Sphinx extension.","package":"Sphinx","optional":false}],"imports":[{"note":"`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.","wrong":"import sphinx_multiversion","symbol":"sphinx_multiversion","correct":"extensions = ['sphinx_multiversion', 'sphinx.ext.autodoc'] # in conf.py"}],"quickstart":{"code":"# conf.py\nimport os\n\nproject = 'My Multi-version Project'\ncopyright = '2024, Your Name'\nversion = '0.1'\nrelease = '0.1.0'\n\nextensions = [\n    'sphinx_multiversion',\n    'sphinx.ext.autodoc',\n]\n\n# Multiversion configuration (adjust regex as needed)\n# Builds documentation for tags matching vX.Y.Z\nsmv_tag_whitelist = r'^v\\d+\\.\\d+\\.\\d+$'\n# Builds documentation for 'main' and 'develop' branches\nsmv_branch_whitelist = r'^(main|develop)$'\n# Default remote to fetch from\nsmv_remote_whitelist = 'origin'\n\n# To build:\n# Run this command from your documentation root (where conf.py is located):\n# sphinx-multiversion . _build/html\n","lang":"python","description":"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."},"warnings":[{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"0.2.0 onwards"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"`pip install sphinx-multiversion` and ensure `'sphinx_multiversion'` is in the `extensions` list in your `conf.py`.","cause":"`sphinx-multiversion` is not installed in the environment or not added to `extensions` in `conf.py`.","error":"ModuleNotFoundError: No module named 'sphinx_multiversion'"},{"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)$'`.","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.","error":"WARNING: [smv] No branches matched 'smv_branch_whitelist' (or 'smv_tag_whitelist')"},{"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.","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`.","error":"sphinx-multiversion: error: unrecognized arguments: . _build/html"},{"fix":"Install Sphinx: `pip install Sphinx`.","cause":"`sphinx-multiversion` internally calls `sphinx-build`. If Sphinx is not installed or not in your system's PATH, this error will occur.","error":"The 'sphinx-build' command was not found. Make sure you have Sphinx installed."},{"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.","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.","error":"jinja2.exceptions.TemplateNotFound: versions.html"}]}