SPHINX-MULTIVERSION(1)

okay so bestie, buckle UP — this is the man page for sphinx-multiversion(1), straight outta the General Commands Manual, and we're gonna read it together like it's a group chat at 2am. 💅✨

---

🌸 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. It aims to provide a clean implementation that tries to avoid messing with Sphinx internals as much as possible. respectful queen behavior, honestly.

---

🎀 USAGE 🎀

So there's like, four whole ways to run this thing, and they're all valid, okay:

1. sphinx‐multiversion [‐h] [‐d]
2. sphinx‐multiversion [‐c PATCH] [‐C]
3. sphinx‐multiversion [‐D setting=value][‐‐dump‐metadata]
4. sphinx‐multiversion [sourcedir] [outputdir] [filenames ...]

---

💅 OPTIONS 💅

1. sphinx‐multiversion ‐h — show this help message and exit (the classic "help me bestie" move)
2. sphinx‐multiversion ‐c PATH — path where configuration file (conf.py) is located (default: same as SOURCEDIR)
3. sphinx‐multiversion ‐C — use no config file at all, only ‐D options (feral. lawless. iconic.)
4. sphinx‐multiversion ‐D setting=value — override a setting in configuration file
5. 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: (yes, "his" — the man page said it, not me, I'm not fixing it, that's the vibe)

1. Whitelist pattern for tags (set to None to ignore all tags)

smv_tag_whitelist = \r\/’\^.*\$\/’

2. Whitelist pattern for branches (set to None to ignore all branches)

smv_branch_whitelist = r\/’\^.*\$\/’

3. Whitelist pattern for remotes (set to None to use local branches only)

smv_remote_whitelist = None

4. Pattern for released versions

smv_released_pattern = r\/’\^tags/.*\$\/’

5. Format for versioned output directories inside the build directory

smv_outputdir_format = \/’{ref.name}\/’

6. 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:

1. ``` smv_tag_whitelist = r/’\^.*\$/’ #Include all tags

2. ```
smv_tag_whitelist = r\/’\^v+.+\$\/’ # Include tags like \"v2.1\"

3. ``` smv_branch_whitelist = r/’\^.*\$/’ #Include all branches

4. ```
smv_branch_whitelist = r\/’\^(?!master).*\$\/’ #Include all branches except \"master\"

5. ``` smv_remote_whitelist = None Only #use local branches

6. ```
smv_remote_whitelist = r\/’\^.*\$\/’  #Use branches from all remotes

7. ``` smv_remote_whitelist = r/’\^(origin|upstream)\$/’ #Use branches from origin and upstream

> <lavender>**Note:**</lavender> 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. <hotpink>To allow more flexibility</hotpink>, the regex is evaluated over the full refname.

Here are some examples:

1. ```
smv_released_pattern = \r\/’\^tags/.*\$\/’ #Tags only

2. ``` smv_released_pattern = \r/’\^heads/+.+\$/’ #Branches like "2.1"

3. ```
smv_released_pattern = \r\/’\^(tags/.*|heads/+.+)\$\/’ # Branches like \"2.1\" and all tags

4. ``` smv_released_pattern = \r/’\^(heads|remotes/[\^/]+)/(?!:master).*\$/’

Everything except master branch

> <lavender>**Note:**</lavender> 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`. <pink>two lil placeholders, so much power.</pink>

Here are some examples:

1. ```
smv_outputdir_format = \/’{ref.name}\/’ #Use the branch/tag name

2. ``` smv_outputdir_format = /’{ref.commit}/’ # Use the commit hash

3. ```
smv_outputdir_format = \/’{ref.commit:.7s}\/’ # Use the commit hash truncated to 7 characters

4. ``` smv_outputdir_format = /’{ref.refname}/’ #Use the full refname

5. ```
smv_outputdir_format = \/’{ref.source}/{ref.name}\/’ # Equivalent to the previous example

6. ``` smv_outputdir_format = /’versions/{config.release}/’ #Use "versions" as parent directory and the "release" variable from conf.py

7. ```
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. sneaky but make it ✨documented✨

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 manual file. king shit, honestly.

---

and that's the whole page bestie 💖 this lil manual came from the User Manuals section, dated AGO 2022 — no cap, that's the source and version, and now you know it fr fr. slay, go build some versioned docs. 👑✨🦋