You're reading the documentation for a development version. For the latest released version, please have a look at 0.3.2.

Configuration

sphinx-multiversion-contrib reads your Sphinx conf.py file for configuration. As usual, you can also override certain options by using -D var=value on the command line.

This is what the default configuration looks like:

# Whitelist pattern for tags (set to None to ignore all tags)
smv_tag_whitelist = r'^.*$'

# Whitelist pattern for branches (set to None to ignore all branches)
smv_branch_whitelist = r'^.*$'

# Whitelist pattern for remotes (set to None to use local branches only)
smv_remote_whitelist = None

# Pattern for released versions
smv_released_pattern = r'^tags/.*$'

# Format for versioned output directories inside the build directory
smv_outputdir_format = '{ref.name}'

# Determines whether remote or local git branches/tags are preferred if their output dirs conflict
smv_prefer_remote_refs = False

You can override all of these values inside your conf.py.

Note

You can check which tags/branches are matched by running sphinx-multiversion-contrib with the --dump-metadata flag. Branches or tags that don’t contain both the sphinx source directory and the conf.py file will be skipped automatically.

Tag/Branch/Remote whitelists

Tags, Branches and Remotes are included by Regular Expressions. Here are some examples:

smv_tag_whitelist = r'^.*$'                   # Include all tags
smv_tag_whitelist = r'^v\d+\.\d+$'            # Include tags like "v2.1"

smv_branch_whitelist = r'^.*$'                # Include all branches
smv_branch_whitelist = r'^(?!master).*$'      # Include all branches except "master"

smv_remote_whitelist = None                   # Only use local branches
smv_remote_whitelist = r'^.*$'                # Use branches from all remotes
smv_remote_whitelist = r'^(origin|upstream)$' # Use branches from origin and upstream

Note

To list values to match, you can use git branch, git tag and git remote.

In addition, sphinx-multiversion-contrib can build the development version of the docs from the current directory, not from a git reference. To do so, provide the name for a development version using the --dev-name option. For example, --dev-name dev will build the development version under name dev. The development version is always marked as not released.

By default, the development version of the docs is stored in the root build directory. You can change this by providing a path relative to the root build directory using the --dev-path option. For example, --dev-path dev/current will build the development version in dev/current subdirectory inside the root build directory.

Release Pattern

A Regular Expression is used to determine if a version of the documentation has been released or if it’s a development version. To allow more flexibility, the regex is evaluated over the full refname.

Here are some examples:

smv_released_pattern = r'^tags/.*$'           # Tags only
smv_released_pattern = r'^heads/\d+\.\d+$'    # Branches like "2.1"
smv_released_pattern = r'^(tags/.*|heads/\d+\.\d+)$'           # Branches like "2.1" and all tags
smv_released_pattern = r'^(heads|remotes/[^/]+)/(?!:master).*$' # Everything except master branch

Note

To list all refnames , you can use:

git for-each-ref --format "%(refname)" | sed 's/^refs\///g'

Output Directory Format

Each version will be built into a seperate subdirectory of the Sphinx output directory. The smv_outputdir_format setting determines the directory structure for the subdirectories. It is a new-style Python formatting string with two parameters - ref and config.

Here are some examples:

smv_outputdir_format = '{ref.name}'        # Use the branch/tag name
smv_outputdir_format = '{ref.commit}'      # Use the commit hash
smv_outputdir_format = '{ref.commit:.7s}'  # Use the commit hash truncated to 7 characters
smv_outputdir_format = '{ref.refname}'     # Use the full refname
smv_outputdir_format = '{ref.source}/{ref.name}'      # Equivalent to the previous example
smv_outputdir_format = 'versions/{config.release}'    # Use "versions" as parent directory and the "release" variable from conf.py
smv_outputdir_format = '{config.version}/{ref.name}'  # Use the version from conf.py as parent directory and the branch/tag name as subdirectory

See also

Have a look at PyFormat for information how to use new-style Python formatting.

Skipping Build

Building docs for a specific version can be skipped if the target directory already exists and --skip-if-outputdir-exists flag is passed to sphinx-multiversion-contrib. It does not check the contents of the directory, only its existence. This can be used to speed up the whole process, so that the docs for older versions are not rebuilt every time.

Overriding Configuration Variables

You can override configuration variables the same way as you’re used to with sphinx-build.

Since sphinx-multiversion-contrib copies the branch data into a temporary directory and builds them there while leaving the current working directory unchanged, relative paths in your conf.py will refer to the path of the version you’re building from, not the path of the version you are trying to build documentation for.

Sometimes it might be necessary to override the configured path via a command line overide. sphinx-multiversion-contrib allows you to insert placeholders into your override strings that will automatically be replaced with the correct value for the version you’re building the documentation for.

Here’s an example for the exhale extension:

sphinx-multiversion docs build/html -D 'exhale_args.containmentFolder=${sourcedir}/api'

Note

Make sure to enclose the override string in single quotes (') to prevent the shell from treating it as an environment variable and replacing it before it’s passed to sphinx-multiversion-contrib.

Note

To see a list of available placeholder names and their values for each version you can use the --dump-metadata flag.