sphinx-versioning [GLOBAL_OPTIONS] build [OPTIONS] REL_SOURCE... DESTINATIONsphinx-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 :option:`--local-conf` argument or sphinx-versions will look at the first conf.py it finds in your :option:`REL_SOURCE` directories. To completely disable using a conf.py file specify the :option:`--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 = TrueThese options apply to to :ref:`build <build-arguments>` sub commands. They must be specified before the build command or else you'll get an error.
.. option:: -c <directory>, --chdir <directory>
Change the current working directory of the program to this path.
.. option:: -g <directory>, --git-root <directory>
Path to directory in the local repo. Default is the current working directory.
.. option:: -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 :option:`REL_SOURCE`
directory within the current working directory. Stops at the first conf.py found if any.
.. option:: -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.
.. option:: -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.
.. option:: -v, --verbose
Enable verbose/debug logging with timestamps and git command outputs. Implies :option:`--no-colors`. If specified
more than once excess options (number used - 1) will be passed to sphinx-build.
The :ref:`build <build-arguments>` sub commands use these arguments.
.. option:: 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.
.. option:: --, 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:
.. code-block:: bash
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:
.. code-block:: python
scv_overflow = ("-A", "html_theme=sphinx_rtd_theme")
The build sub command builds all versions locally. It always gets the latest branches and tags from origin and
builds those doc files.
In addition to the :ref:`common arguments <common-positional-arguments>`:
.. option:: 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.
These options are available for the build sub command:
.. option:: -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 :option:`--banner-main-ref` is used.
This setting may also be specified in your conf.py file. It must be a boolean:
.. code-block:: python
scv_banner_greatest_tag = True
.. option:: -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
:option:`--banner-main-ref` is used.
This setting may also be specified in your conf.py file. It must be a boolean:
.. code-block:: python
scv_banner_recent_tag = True
.. option:: -b, --show-banner, scv_show_banner
Show a warning banner. Enables the :ref:`banner` feature.
This setting may also be specified in your conf.py file. It must be a boolean:
.. code-block:: python
scv_show_banner = True
.. option:: -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:
.. code-block:: python
scv_banner_main_ref = 'feature_branch'
.. option:: -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:
.. code-block:: python
scv_invert = True
.. option:: -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:
.. code-block:: python
scv_priority = 'branches'
.. option:: -r <ref>, --root-ref <ref>, scv_root_ref
The branch/tag at the root of :option:`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:
.. code-block:: python
scv_root_ref = 'feature_branch'
.. option:: -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 <http://semver.org/>`_, 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:
.. code-block:: python
scv_sort = ('semver',)
.. option:: -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 :option:`--root-ref` is used.
This setting may also be specified in your conf.py file. It must be a boolean:
.. code-block:: python
scv_greatest_tag = True
.. option:: -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
:option:`--root-ref` is used.
This setting may also be specified in your conf.py file. It must be a boolean:
.. code-block:: python
scv_recent_tag = True
.. option:: -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:
.. code-block:: python
scv_whitelist_branches = ('master', 'latest')
.. option:: -W <pattern>, --whitelist-tags <pattern>, scv_whitelist_tags
Same as :option:`--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:
.. code-block:: python
scv_whitelist_tags = (re.compile(r'^v\d+\.\d+\.\d+$'),)