Step 1: Sphinx extension

In your Documentation’s conf.py, add 'docs_versions_menu' to your extensions.

That’s it.

See the Docs Versions Menu’s conf.py for an example.

This will inject a javascript file docs-versions-menu.js into every generated page of the documentation. When the page is loaded, the script searches upward from the current URL until it finds a versions.json file, then renders the versions menu from that data.

The menu works on any web host where versions.json is served from the webroot of the hosted documentation (e.g. the root of a gh-pages branch, or the root of a static hosting path). It will not appear when viewing documentation locally (from the filesystem).

Sphinx themes

For best results, use the Read the Docs Sphinx Theme (sphinx_rtd_theme). This is the default theme for documentation hosted on readthedocs.org (RTD). However, it can also be used when hosting documentation outside of RTD!

Especially for documentation that includes extensive reference (API) content, the RTD theme provides a much better visual structure than Sphinx’ default alabaster theme which is also used on this page [1].

With sphinx_rtd_theme, the versions menu will be displayed as part of the navigation bar on the left side of the screen (just like on RTD). For any other Sphinx theme, the versions menu will be shown as a “badge” in the bottom right corner of the page (like on this page; and, like for documentation hosted on RTD that doesn’t use the default theme).

The theme is automatically detected based on the value of html_theme in the Sphinx conf.py file. If this is anything other than "sphinx_rtd_theme", the badge-style versions menu is used. This implies that in addition to the javascript file docs-versions-menu.js, a badge_only.css file as well as a number of Font Awesome files will be included in the generated documentation.

Settings in conf.py

The settings for the Sphinx extensions are taken from a dict docs_versions_menu_conf in Sphinx’ conf.py configuration file.

The dict may contain the following keys:

  • github_project_url (str): The full URL to the project on Github, e.g. "https://github.com/user/project". When set, the menu shows links to the project home and issue tracker. Defaults to None (no Github links shown).

  • badge_only (bool): Whether to render the version menu as a “badge” in the lower right corner (defaults to True unless html_theme is "sphinx_rtd_theme")

  • menu_title (str): The label to be shown in to left corner of the full versions menu (if not badge_only). Defaults to “Docs”.

Do not use the setting badge_only=False together with the sphinx_rtd_theme. In order to avoid the badge_only.css and font files being injected if you are using a completely custom template, do set badge_only=False and supply your own CSS files e.g. in a html_static_path folder.