Program Options

If you do need to customize docs-versions-menu’s behavior, there are two options:

  1. Call the docs-versions-menu executable with explicit command line options

  2. Set DOCS_VERSIONS_MENU_* environment variables, each variable corresponding to a command line option

The latter option is generally preferred.

docs-versions-menu

Usage

docs-versions-menu [OPTIONS]

Options

--version

Show the version and exit.

--debug

enable debug logging [env var DOCS_VERSIONS_MENU_DEBUG]

-o, --outfile <OUTFILE>

File to which to write json data [env var DOCS_VERSIONS_MENU_OUTFILE; default: versions.json]

--default-branch <DEFAULT_BRANCH>

The name or possible names of the default branch for the project. If the project has no public releases, the default index.html should forward to the first available default branch. Traditionally, most projects have used ‘master’ as the default branch. More recently, the name ‘main’ has become standard. [env var DOCS_VERSIONS_MENU_DEFAULT_BRANCH; default: master, main]

--versions <SPEC>

Specification of versions to be included in the menu, from oldest/lowest priority to newest/highest priority. The newest/highest priority items will be shown first. See the online documentation for the SPEC syntax. [env var DOCS_VERSIONS_MENU_VERSIONS; default: (<branches> != <default-branch>), <releases>, <default-branch>]

--latest <SPEC>

Specification of which version is considered the “latest public release”. If it exists, the main index.html should forward to this version, and warnings e.g. for “outdated” versions should link to it. See the online documentation for the SPEC syntax. [env var DOCS_VERSIONS_MENU_LATEST; default: (<public-releases>)[-1]]

--warning <NAME SPEC>

Define a warning. The NAME is a lowercase label that will appear in the warnings data in versions.json and maybe be picked up by the javascript rendering warning in the HTML output. The SPEC is a folder specification for all folders that should show the warning. See the online documentation for the syntax of SPEC. The SPEC should give given as a quoted string. This option may be given multiple times.If specified via an environment variable, use the form "NAME: SPEC; NAME: SPEC; …". Any colons and semi-colons in NAME and SPEC must be escaped in this case. See the online documentation for details. [env var DOCS_VERSIONS_MENU_WARNING]

--label <SPEC LABELTEMPLATE>

Set a template for labels in the versions menu. The LABELTEMPLATE applies to all folders matching the given SPEC. See the online documentation for the syntax of SPEC. The LABELTEMPLATE is rendered with Jinja, receiving the folder name. See the online documentation for details. This option may be given multiple times. If specified via an environment variables, use the form "SPEC: LABELTEMPLATE; SPEC: LABELTEMPLATE; …". Any colons and semi-colons in SPEC and LABELTEMPLATE must be escaped in this case. See the online documentation for details. [env var DOCS_VERSIONS_MENU_LABEL]

--write-index-html, --no-write-index-html

Whether to write an index.html that forwards to the latest public release. In the config file, override this as write_index_html=False. [env var DOCS_VERSIONS_MENU_WRITE_INDEX_HTML; default: True]

--write-versions-py, --no-write-versions-py

Whether to write a script versions.py to the root of the gh-pages branch for regenerating versions.json. This is useful for maintenance on the gh-pages branch, e.g., removing outdated version. [env var DOCS_VERSIONS_MENU_WRITE_VERSIONS_PY; default: True]

--ensure-no-jekyll, --ignore-no-jekyll

Whether to check that a .nojekyll file exist and create it otherwise. In the config file, override this as ensure_no_jekyll=False. [env var DOCS_VERSIONS_MENU_ENSURE_NO_JEKYLL; default: True]

--downloads-file <FILE>

The name of the file inside of each folder from which to read the download links. Each line in the file must be of the form [label]: url. To disable download links, use --no-downloads-file or set the environment variable to an empty string. [env var DOCS_VERSIONS_MENU_DOWNLOADS_FILE; default: _downloads]

--no-downloads-file

Disable the downloads file. In the config file, use downloads_file = False. Or, using an environment variable, set DOCS_VERSIONS_MENU_DOWNLOADS_FILE="".

--suffix-latest <suffix_latest>

Suffix for the label of the latest public release. This is used in addition to any label set via the --label option [env var DOCS_VERSIONS_MENU_SUFFIX_LATEST; default:  (latest)]

Debugging

If the docs-versions-menu command behaves unexpectedly, set the environment variable

DOCS_VERSIONS_MENU_DEBUG=true

or use the --debug option.

Make sure to include the debug output when reporting bugs.

Folders

The entries in the versions menu are based on the folders that are present in the deployed documentation root. We assume here that the folder names correspond to branch or tag names in the project repository. This is irrespective of the label that appears for given foler in the menu, see below.

By default, the versions menu lists the folder for the default branch (main or master, see --default-branch) first, then any releases from newest to oldest, and then any non-release branches in reverse-alphabetical order. Having the “newest” releases appear first matches the behavior of Read-the-Docs.

The folders that are listed in the versions menu and their order can be customized via the --versions flag (DOCS_VERSIONS_MENU_VERSIONS environment variable). This receives a folder specification as an argument that specifies the folders to appear in the menu in reverse order (bottom/right to top/left).

To un-reverse the default order of folders in the menu, so that the newest versions and the default branch appear last, you would set

DOCS_VERSIONS_MENU_VERSIONS: '((<branches> not in <default-branch>), <releases>, <default-branch>)[::-1]'

in the definitions of environment variables.

Custom warning messages

By default, the docs_versions_menu extension injects warnings in the rendered HTML files, within the following types of folders:

  • an ‘outdated’ warning for <releases> older than the latest public release (identified by --latest)

  • an ‘unreleased’ warning for <branches> (anything that is not a PEP 440-conforming release), or <local-releases> (typically not used)

  • a ‘prereleased’ warning for anything considered a pre-release by PEP 440, e.g. v1.0.0-rc1

Which folders are included in the above three categories can be modified via the --warning option. This options receives two arguments, a “warning label” string (the above ‘outdated’, ‘unreleased’, or ‘prereleased’), and a folder specification for the folders to which the warning should apply. The option can be given multiple times. An empty specification would disable the warning, e.g.

docs-versions-menu --warning prereleased ''

to disable the warning message on pre-releases.

It is also possible to define entirely new warning labels using --warning. For example,

docs-versions-menu --warning post '<post-releases>'

would define a warning ‘post’ for all post-releases.

The information about which folders should display which warnings is stored internally in the resulting versions.json file, in a dict ‘warnings’ that maps folder names to a list of warning labels.

To actually show this new custom warning, the docs-versions-menu.js template would have to be modified to pick up on the ‘post’ label.

Similarly to Menu labels, when configuring the warnings via the DOCS_VERSIONS_MENU_WARNING environment variable, multiple --warning options are combined into a single value, separated by semicolons, and the warning label and folder specification separated by a colon.

For the above two options, you might include the following the definition of the environment variables in a Github Actions workflow:

DOCS_VERSIONS_MENU_WARNING: 'post: <post-relases>; prereleased:'