History

0.6.0 (2026-06-30)

  • Updated pyparsing API to use non-deprecated function names (DelimitedList, one_of, set_parse_action, parse_string, as_list)

  • Removed jQuery dependency from the versions-menu JavaScript (#33, #25); the sphinxcontrib.jquery workaround is no longer needed

  • The versions menu now works on any web host, not just Github Pages (#25): the script auto-discovers versions.json by walking up the URL path. The json_file and current_folder template variables are removed; github_project_url auto-detection from github.io URLs is preserved as a runtime fallback but can be overridden via docs_versions_menu_conf

  • Dropped support for Python 3.9 (EOL)

  • Added support for Python 3.13

  • Dropped support for Sphinx < 7.2

  • Dropped support for Jinja2 < 3.0

  • Dropped support for packaging < 17.0

  • Dropped support for pyparsing < 3.1 (tightened from < 3.0)

Migration notes

  • If you previously added sphinxcontrib.jquery to extensions as a workaround for the missing jQuery in Sphinx >= 6.0, you may now remove it.

  • If you have a custom docs-versions-menu.js_t template that uses the json_file or current_folder template variables, those variables no longer exist and must be removed or replaced with the new runtime auto-discovery approach.

  • To show a Github link in the versions menu on a non-Github Pages host, set github_project_url explicitly in docs_versions_menu_conf.

  • Existing deployed folders (e.g., on a gh-pages branch) may benefit from manually updating the docs-versions-menu.js script, as described in “Interactive maintenance” in the deployment documentation. Without this, only newly built folders benefit from the changes in #25.

0.5.2 (2023-04-19)

  • Compatibility with packaging >= 22.0 (#27, #32)

0.5.1 (2023-01-25)

  • Pin packaging dependency to < 22.0 (#27, #28)

0.5.0 (2022-11-17)

  • Renamed project to docs-versions-menu (#13)

  • Changed: Removed support for a config file (#9)

  • Dropped support for Python 3.5 and Python 3.6

  • Added support for Python 3.10 and 3.11

  • Improvements to the workflow and documentation.

  • Update of conda-feedstock

Migration from doctr-versions-menu

The doctr-versions-menu package was renamed to docs-versions-menu to reflect that Travis and thus Doctr is no longer a viable option to deploy documentation. Switching from doctr-versions-menu to docs-versions-menu requires the following steps:

  • Consider switching from Travis to Github Actions

  • Update your Sphinx configuration (conf.py):

    • Rename the doctr_versions_menu_conf dictionary of settings to docs_versions_menu_conf.

    • Change the name of the doctr_versions_menu extension in the extensions list to docs_versions_menu.

    • If using a custom doctr-versions-menu.js_t template, rename the file to docs-versions-menu.js_t

  • Update your continuous-integration setup:

    • Replace the doctr-versions-menu package with docs-versions-menu in the project requirements (setup.py/setup.cfg)

    • Replace the installation of the doctr-versions-menu package with docs-versions-menu in your CI script or environment files

    • Replace calls to the doctr-versions-menu executable with calls to docs-versions-menu

    • If using environment variables for configuration, change the DOCTR_VERSIONS_MENU prefix to DOCS_VERSIONS_MENU

  • For any project using a doctr-versions-menu.conf file in the gh-pages root, set up equivalent DOCS_VERSIONS_MENU_* environment variables

To ease migration, the new docs-versions-menu will still process doctr_versions_menu_conf, DOCTR_VERSIONS_MENU environment variables, and a doctr-versions-menu.js_t template, while emitting a warning. This limited backwards-compatibility may be removed in later versions.

0.4.1 (2021-03-18)

Note: this release was under the project name doctr-versions-menu.

  • Fixed: The doctr-versions-menu exectuable no longer fails when run outside of a git repository (#15, thanks to Alexander Blech)

  • Fixed: Custom doctr-versions-menu.js_t template were being ignored (#18)

0.4.0 (2020-12-14)

Note: this release was under the project name doctr-versions-menu.

  • Added: The label in the top left corner of the version menu can now be configured in conf.py (setting menu_title).

  • Added: --default-branch option, <default-branch> group for folder specifications, and default-branch field in versions.json (#12)

  • Changed: The default --versions now uses <default-branch>, automatically picking up on either “master” or “main” as the default branch (#12)

  • Changed: The default template for index.html now automatically forwards to the default-branch (based on the --default-branch option, instead of just “master”), or the first available branch if there is no released version (#12)

This release addresses two major compatibility issues:

  1. Both git and Github have recently switched the name of the default branch from “master” to “main”. This release adds support for new projects using “main” as their default branch.

  2. As of December 2020, Travis CI has stopped their support for open source. Consequently, Doctr can no longer be used to deploy documentation at no cost. This release adds rudimentary support for deploying the documenation with Github Actions instead of Doctr, see Deployment with Github Actions.

0.3.0 (2020-08-03)

Note: this release was under the project name doctr-versions-menu.

  • Added: --no-downloads-file option, downloads_file = False in config. (#4, thanks to Tyler Pennebaker)

  • Fixed: versions.py on gh-pages branch was not being committed (#5)

  • Fixed: Compatibility with any pyparsing version >= 2.0.2 (#8, thanks to Hugo Slepicka)

  • Added: The doctr-versions-menu executable can now be configured through environment variables. This allows to keep configuration on the source branch, in the .travis.yml file (#6, thanks to Tyler Pennebaker)

  • The Doctr Versions Menu package can now be installed via conda (thanks to Hugo Slepicka)

0.2.0 (2020-03-14)

Note: this release was under the project name doctr-versions-menu.

  • Added: --versions option for customizing which folders appear in the versions menu and in which order.

  • Added: --label option for customizing the labels appearing the versions menu

  • Added: --warning option for customizing on which folders specific warnings are displayed

  • Added: --latest option for configuring which folder is the “latest stable release”

  • Added: Write a script versions.py to the root of the gh-pages branch (--write-versions-py option)

  • Changed: unreleased and pre-released versions now show different warnings by default

  • Changed: index.html template is now rendered with full version_data

  • Changed: development/pre-release versions now longer have the “dev” suffix in the versions menu by default

  • Changed: The versions menu now uses the same ordering of versions as Read-the-Docs, by default: the folders are ordered from most current to least current.

  • Changed: internal format of versions.json

  • Removed: --default-branch option. This is replaced by the new --latest option and enhanced template rendering of the index.html

  • Removed: --suffix-unreleased option. This can now be achieved via the --label option

This is a major release that breaks backwards compatibility.

Specifically, due to the changes in versions.json, when upgrading from older versions, it may be necessary to replace doctr-versions-menu.js files in existing folders in a project’s gh-pages branch.

0.1.0 (2020-01-11)