Settings¶

sphinx-versioning [GLOBAL_OPTIONS] build [OPTIONS] REL_SOURCE... DESTINATION

sphinx-versions reads settings from two sources:

Your Sphinx conf.py file.
Command line arguments.

Command line arguments always override anything set in conf.py. You can specify the path to conf.py with the --local-conf argument or sphinx-versions will look at the first conf.py it finds in your REL_SOURCE directories. To completely disable using a conf.py file specify the --no-local-conf command line argument.

Below are both the command line arguments available as well as the conf.py variable names sphinx-versions looks for. All conf.py variable names are prefixed with scv_.

An example:

# conf.py
author = 'Your Name'
project = 'My Project'
scv_greatest_tag = True

Global Options¶

These options apply to to build sub commands. They must be specified before the build command or else you’ll get an error.

-c <directory>, --chdir <directory>¶: Change the current working directory of the program to this path.

-g <directory>, --git-root <directory>¶: Path to directory in the local repo. Default is the current working directory.

-l <file>, --local-conf <file>¶

Path to conf.py for sphinx-versions to read its config from. Does not affect conf.py loaded by sphinx-build.

If not specified the default behavior is to have sphinx-versions look for a conf.py file in any REL_SOURCE directory within the current working directory. Stops at the first conf.py found if any.

-L, --no-local-conf¶: Disables searching for or loading a local conf.py for sphinx-versions settings. Does not affect conf.py loaded by sphinx-build.

-N, --no-colors¶: By default INFO, WARNING, and ERROR log/print statements use console colors. Use this argument to disable colors and log/print plain text.

-v, --verbose¶: Enable verbose/debug logging with timestamps and git command outputs. Implies --no-colors. If specified more than once excess options (number used - 1) will be passed to sphinx-build.

Common Positional Arguments¶

The build sub commands use these arguments.

REL_SOURCE¶

The path to the docs directory relative to the git root. If the source directory has moved around between git tags you can specify additional directories.

This cannot be an absolute path, it must be relative to the root of your git repository. Sometimes projects move files around so documentation might not always have been in one place. To mitigate this you can specify additional relative paths and the first one that has a conf.py will be selected for each branch/tag. Any branch/tag that doesn’t have a conf.py file in one of these REL_SOURCEs will be ignored.

--, scv_overflow¶

It is possible to give the underlying sphinx-build program command line options. sphinx-versions passes everything after -- to it. For example if you changed the theme for your docs between versions and want docs for all versions to have the same theme, you can run:

sphinx-versioning build docs docs/_build/html -- -A html_theme=sphinx_rtd_theme

This setting may also be specified in your conf.py file. It must be a tuple of strings:

scv_overflow = ("-A", "html_theme=sphinx_rtd_theme")

Build Arguments¶

The build sub command builds all versions locally. It always gets the latest branches and tags from origin and builds those doc files.

Positional Arguments¶

In addition to the common arguments:

DESTINATION¶

The path to the directory that will hold all generated docs for all versions.

This is the local path on the file sytem that will hold HTML files. It can be relative to the current working directory or an absolute directory path.

Options¶

These options are available for the build sub command:

-a, --banner-greatest-tag, scv_banner_greatest_tag¶

Override banner-main-ref to be the tag with the highest version number. If no tags have docs then this option is ignored and --banner-main-ref is used.

This setting may also be specified in your conf.py file. It must be a boolean:

scv_banner_greatest_tag = True

-A, --banner-recent-tag, scv_banner_recent_tag¶

Override banner-main-ref to be the most recent committed tag. If no tags have docs then this option is ignored and --banner-main-ref is used.

This setting may also be specified in your conf.py file. It must be a boolean:

scv_banner_recent_tag = True

-b, --show-banner, scv_show_banner¶

Show a warning banner. Enables the Banner Message feature.

This setting may also be specified in your conf.py file. It must be a boolean:

scv_show_banner = True

-B <ref>, --banner-main-ref <ref>, scv_banner_main_ref¶

The branch/tag considered to be the latest/current version. The banner will not be displayed in this ref, only in all others. Default is master.

If the banner-main-ref does not exist or does not have docs the banner will be disabled completely in all versions. Docs will continue to be built.

This setting may also be specified in your conf.py file. It must be a string:

scv_banner_main_ref = 'feature_branch'

-i, --invert, scv_invert¶

Invert the order of branches/tags displayed in the sidebars in generated HTML documents. The default order is whatever git prints when running “git ls-remote –heads –tags”.

This setting may also be specified in your conf.py file. It must be a boolean:

scv_invert = True

-p <kind>, --priority <kind>, scv_priority¶

kind may be either branches or tags. This argument is for themes that don’t split up branches and tags in the generated HTML (e.g. sphinx_rtd_theme). This argument groups branches and tags together and whichever is selected for kind will be displayed first.

This setting may also be specified in your conf.py file. It must be a string:

scv_priority = 'branches'

-r <ref>, --root-ref <ref>, scv_root_ref¶

The branch/tag at the root of DESTINATION. Will also be in subdirectories like the others. Default is master.

If the root-ref does not exist or does not have docs, sphinx-versioning will fail and exit. The root-ref must have docs.

This setting may also be specified in your conf.py file. It must be a string:

scv_root_ref = 'feature_branch'

-s <value>, --sort <value>, scv_sort¶

Sort versions by one or more certain kinds of values. Valid values are semver, alpha, and time.

You can specify just one (e.g. “semver”), or more. The “semver” value sorts versions by Semantic Versioning, with the highest version being first (e.g. 3.0.0, 2.10.0, 1.0.0). Non-semver branches/tags will be sorted after all valid semver formats. This is where the multiple sort values come in. You can specify “alpha” to sort the remainder alphabetically or “time” to sort chronologically (most recent commit first).

This setting may also be specified in your conf.py file. It must be a tuple of strings:

scv_sort = ('semver',)

-t, --greatest-tag, scv_greatest_tag¶

Override root-ref to be the tag with the highest version number. If no tags have docs then this option is ignored and --root-ref is used.

This setting may also be specified in your conf.py file. It must be a boolean:

scv_greatest_tag = True

-T, --recent-tag, scv_recent_tag¶

Override root-ref to be the most recent committed tag. If no tags have docs then this option is ignored and --root-ref is used.

This setting may also be specified in your conf.py file. It must be a boolean:

scv_recent_tag = True

-w <pattern>, --whitelist-branches <pattern>, scv_whitelist_branches¶

Filter out branches not matching the pattern. Can be a simple string or a regex pattern. Specify multiple times to include more patterns in the whitelist.

This setting may also be specified in your conf.py file. It must be a tuple of either strings or re.compile() objects:

scv_whitelist_branches = ('master', 'latest')

-W <pattern>, --whitelist-tags <pattern>, scv_whitelist_tags¶

Same as --whitelist-branches but for git tags instead.

This setting may also be specified in your conf.py file. It must be a tuple of either strings or re.compile() objects:

scv_whitelist_tags = (re.compile(r'^v\d+\.\d+\.\d+$'),)