ScyllaDB University Live | Free Virtual Training Event
Learn more
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB Sphinx Theme Configuration Multiversion options

Caution

You're viewing documentation for a previous version of ScyllaDB Sphinx Theme. Switch to the latest stable version.

Multiversion options¶

The toolchain adds by default the extension sphinx-multiversion for building self-hosted versioned documentation.

On this page, you will learn:

  • How to list new versions.

  • How to define a stable url.

  • How to preview local changes with multiversion.

  • How to preview production builds.

  • How to disable multiversion support.

Listing new versions¶

Caution

Maintaining multiple versions is expensive. Consider listing docs for new versions only if the release introduces relevant breaking changes reflected in the documentation. For example, it’s preferable to build docs for a major release rather than one release per patch.

The settings TAGS and BRANCHES in conf.py defines which versions are supported:

  • BRANCHES: List of git branches, separated by a comma. For example, BRANCHES= ['master'] builds docs for the master branch.

  • TAGS: List of git tags, separated by a comma. For example, TAGS = ['3.22.0', '3.21.0'] builds docs for the tags 3.22.0 and 3.21.0.

Tip

If you maintain a branch for each release (e.g. branch-3.22), we recommended building docs for the branch and not for tags. This will allow you to backport documentation changes if needed without having to update the tag reference.

The setting LATEST_VERSION in conf.py defines which branch or tag is considered the latest. This is used to redirect users to the latest version of the docs automatically once they open the main project URL.

For example, if you want to build docs for the tags 3.22.0 and 3.21.0, master branch, the configuration file conf.py should look like this:

TAGS = ['3.22.0', '3.21.0']
BRANCHES = ['master']
LATEST_VERSION = '3.22.0'

The extension allows configuring additional settings. To know more about them, refer to sphinx-multiversion documentation.

Defining a stable URL¶

We encourage every project to rename the latest version output directory to stable. The purpose is to have default documentation links that do not change, which is beneficial for SEO purposes and referencing docs on other websites.

You can override the latest version output directory via the configuration file conf.py with the setting smv_rename_latest_version:

smv_latest_version = LATEST_VERSION  # Use the branch/tag name
smv_rename_latest_version = 'stable' # Use the commit hash

Defining unstable versions¶

Suppose you want to build docs for a version of the software you have not released yet (e.g. master). In this case, you can mark the version as unstable in the conf.py file.

BRANCHES = ['master']
UNSTABLE_VERSIONS = ['master']

By doing so, the warning message that appears at the top of the page will change to:

../_images/unstable.png

Defining deprecated versions¶

Suppose you want to build docs for a version of the software you don’t support anymore. In this case, you can mark the version as deprecated in the conf.py file.

TAGS = ['3.2.0']
DEPRECATED_VERSIONS = ['3.2.0']

By doing so, the warning message that appears at the top of the page will change to:

../_images/deprecated.png

Previewing local changes with multiversion¶

The multiversion feature is primarily designed to generate production builds and is extensively used in CI pipelines.

To preview the latest local changes, the make preview command is recommended over the multiversion feature.

However, if you still need to preview the latest local changes with the multiversion feature enabled, follow these steps:

  1. Open conf.py and set smv_remote_whitelist to None:

    smv_remote_whitelist = None
    
  2. In the same file, add your current branch’s name to the BRANCHES list and set it as the latest version. For example:

    BRANCHES = ["my-local-branch"]
    LATEST_VERSION = "my-local-branch"
    
  3. Run the command make multiversionpreview.

Previewing production builds¶

To preview production builds locally:

  1. Create a temporal folder and move to it:

    mktemp
    cd <PATH_TO_TEMP_FOLDER>
    
  2. Clone the repository you wish to preview, along with all its branches and tags, into the temporary folder:

    git clone https://github.com/username/repository.git
    cd repository
    git branch -r | grep -v '\->' | while read remote; do git branch --track "${remote#origin/}" "$remote"; done
    git fetch --all
    

    Note

    If the repository is a personal fork, you need to synchronize all branches listed in the conf.py file with the upstream repository first. For more information, see Sync Fork.

  3. Run the command make multiversionpreview.

  4. Open http://0.0.0.0:5500/ with your preferred browser.

  5. Once you are finished, remember to delete the temporary folder.

Disabling multiversion support¶

To disable multiversion support:

  1. Set the settings smv_tag_whitelist and smv_branch_whitelist in conf.py to None.

    smv_tag_whitelist = None
    smv_branch_whitelist = None
    

    or:

    TAGS = []
    smv_tag_whitelist = multiversion_regex_builder(TAGS)
    BRANCHES = []
    smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
    
  2. On .github/workflows/pages.yml, change the command make multiversion for make dirhtml.

Was this page helpful?

PREVIOUS
Page options
NEXT
Markdown support
  • Create an issue
  • Edit this page

On this page

  • Multiversion options
    • Listing new versions
    • Defining a stable URL
    • Defining unstable versions
    • Defining deprecated versions
    • Previewing local changes with multiversion
    • Previewing production builds
    • Disabling multiversion support
ScyllaDB Sphinx Theme
  • 1.6
    • 1.8
    • 1.7
    • 1.6
    • 1.5
    • 1.4
    • 1.3
    • 1.2
    • 1.1
  • Getting started
    • Toolchain
    • Installation
    • Quickstart
  • Configuration
    • Template options
    • Page options
    • Multiversion options
    • Markdown support
    • Redirects support
    • Search support
  • Commands
  • Deployment
    • Production deployment
    • Pull requests previews
  • Examples
    • Admonitions
    • Collapse
    • Code blocks
    • Glossary
    • Headings
    • Hero box
    • Includes
    • Images
    • Labels
    • Links
    • Lists
    • Panel box
    • Substitutions
    • Tables
    • Tabs
    • Text
    • TOC
    • Topic box
    • Versions
  • Upgrade guides
    • Migrating from 1.5 to 1.6
    • Migrating from 1.4 to 1.5
    • Migrating from 1.3 to 1.4
    • Migrating from 1.2 to 1.3
    • Migrating from 1.1 to 1.2
    • Migrating from 1.0 to 1.1
    • Migrating from 0.x to 1.0
    • Changelog
  • Contribute
    • Contribute to the documentation
    • Contribute to the theme
    • Source Code
Docs Tutorials University Contact Us About Us
© 2025 ScyllaDB | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 01 Apr 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6
Ask AI