Step 1: Sphinx extension

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

That’s it.

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

This will inject a javascript file doctr-versions-menu.js into every generated page of the documentation that displays a versions menu when the documentation is hosted on Github Pages (the gh-pages branch of the project repository). The contents of the menu is derived from a file versions.json that must be present in the root of gh-pages.

Note

By default, the versions menu will only appear when the documentation is viewed at a Github Pages URL (https://<username>.github.io/<project>/<version>/) and if a file versions.json is present in the <project> folder (that is, the root of the gh-pages branch). It will not appear when viewing documentation locally.

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 doctr-versions-menu.js, a badge_only.css file as well as a number of Font Awesome files will be included in the generated documentation.

1

The alabaster theme is used here to match the Doctr documentation, and also to serve as a self-test for a badge-style versions menu. A version of this documentation using the RTD theme is available through the versions menu.

Customization

The doctr_versions_menu extension does not require any settings. However, you may fully customize the versions menu by placing a Jinja template file doctr-versions-menu.js_t in a folder listed in your templates_path.

This template will be rendered to produce doctr-versions-menu.js using values from a dictionary doctr_versions_menu_conf in your Sphinx conf.py file. Values in this dictionary may overwrite the following defaults used in the default template:

  • json_file (str): The local (absolute) path to the json file that contains version information. Defaults to /<project>/versions.json with <project> dynamically set based on the current Github Pages URL (https://<username>.github.io/<project>/<version>/...)

  • github_project_url (str): The full URL to the project on Github. By default, this is dynamically derived from the current Github Pages URL (see above).

  • current_folder (str): The name of the current folder. By default, dynamically set to the <version> from the current Github Pages URL (see above).

  • 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 “Doctr”.

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.