Configuration

sphinx-multiversion 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 an override all of these values inside you conf.py.

Note

You can check which tags/branches are matched by running sphinx-multiversion with the --dump-metadata flag.

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.

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-stye Python formatting.