SPHINX-MULTIVERSION

NAME

sphinx-multiversion - add support for multiple version to sphinx

SYNOPSIS

sphinxâmultiversion [POSITION] [argument]

DESCRIPTION

sphinxâmultiversion â Sphinx extension for building selfâhosted versioned documentaâ
tion. Aims to provide a clean implementation that tries to avoid messing with Sphinx
internals as much as possible.

USAGE

a) sphinxâmultiversion [âh] [âd]

b) sphinxâmultiversion [âc PATCH] [âC]

c) sphinxâmultiversion [âD setting=value][ââdumpâmetadata]

d) sphinxâmultiversion [sourcedir] [outputdir] [filenames ...]

OPTIONS

a) sphinxâmultiversion âh
show this help message and exit

b) sphinxâmultiversion âc PATH
path where configuration file (conf.py) is located (default: same as SOURCEDIR)

c) sphinxâmultiversion âC
use no config file at all, only âD options

d) sphinxâmultiversion âD setting=value
override a setting in configuration file

e) sphinxâmultiversion ââdumpâmetadata
dump generated metadata and exit

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.
his is what the default configuration looks like:

a) Whitelist pattern for tags (set to None to ignore all tags)
smv_tag_whitelist = \r\/â\ˆ.*\$\/â

b) Whitelist pattern for branches (set to None to ignore all branches)
smv_branch_whitelist = r\/â\ˆ.*\$\/â

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

d) Pattern for released versions
smv_released_pattern = r\/â\ˆtags/.*\$\/â

e) Format for versioned output directories inside the build directory
smv_outputdir_format = \/â{ref.name}\/â

f) etermines whether remote or local git branches/tags are preferred if their output dirs conflict
smv_prefer_remote_refs = False

Note:
You can check which tags/branches are matched by running sphinxâmultiversion 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. You can override all of
these values inside your conf.py.

EXAMPLES

Tag/Branch/Remote whitelists

Tags, Branches and Remotes are included by Regular Expressions Here are some examâ ples:

a) smv_tag_whitelist = r\/â\ˆ.*\$\/â #Include all tags

b) smv_tag_whitelist = r\/â\ˆv+.+\$\/â # Include tags like \"v2.1\"

c) smv_branch_whitelist = r\/â\ˆ.*\$\/â #Include all branches

d) smv_branch_whitelist = r\/â\ˆ(?!master).*\$\/â #Include all branches except \"master\"

e) smv_remote_whitelist = None Only #use local branches

f) smv_remote_whitelist = r\/â\ˆ.*\$\/â #Use branches from all remotes

g) 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:

a) smv_released_pattern = \r\/â\ˆtags/.*\$\/â #Tags only

b) smv_released_pattern = \r\/â\ˆheads/+.+\$\/â #Branches like \"2.1\"

c) smv_released_pattern = \r\/â\ˆ(tags/.*|heads/+.+)\$\/â # Branches like \"2.1\" and all tags

d) 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 separate subdirectory of the Sphinx output direcâ
tory. 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:

a) smv_outputdir_format = \/â{ref.name}\/â #Use the branch/tag name

b) smv_outputdir_format = \/â{ref.commit}\/â # Use the commit hash

c) smv_outputdir_format = \/â{ref.commit:.7s}\/â # Use the commit hash truncated to 7 characters

d) smv_outputdir_format = \/â{ref.refname}\/â #Use the full refname

e) smv_outputdir_format = \/â{ref.source}/{ref.name}\/â # Equivalent to the previous example

f) smv_outputdir_format = \/âversions/{config.release}\/â #Use \"versions\" as parent directory
and the \"release\" variable from conf.py

g) smv_outputdir_format = \/â{config.version}/{ref.name}\/â #Use the version from conf.py as
parent directory and the branch/tag name as subdirectory

Overriding Configuration Variables

You can override configuration variables the same way as youâre used to with sphinxâ
build. Since sphinxâmultiversion 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
override. sphinxâmultiversion 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=\$
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. To see a list of available placeholder names and their values
for each version you can use the ââdumpâmetadata flag.

SEE ALSO

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

AUTHOR

Jan Holthuis jan.holthuis@ruhrâuniâbochum.de â¨mailto:jan.holthuis@ruhrâuniâ
bochum.deâ© Based on https://github.com/Holzhaus/sphinxâ multiversion/blob/masâ
ter/README.md.

Josenilson Ferreira da Silva nilsonfsilva@hotmail.com â¨mailto:nilsonfsilva@hotâ
mail.comâ© Created this manâpage on markdown, and used goâmd2man to generate the manâ
ual file.