docs-versions-menu 0.5.0rc2

A versions menu for Sphinx-based documentation

Docs-Versions-Menu

A versions-menu for Sphinx-based documentation.

Historically, many open source projects have hosted their documentation on Read the Docs (RTD). However, RTD has a fixed build process that is essentially limited to just running Sphinx. Moreover, RTD will inject advertisements into your documentation.

A more flexible approach is to build the documentation with continuous integration (e.g., Github Actions) and to deploy the result to Github Pages or any other static site hosting. There are no restrictions on the build process: it may involve make, tox, latex, or any number of custom scripts to augment Sphinx.

The one difficulty that comes with self-hosting project documentation is that out of the box, there is no support for showing multiple releases or branches of the project. This project aims to remedy this. It provides a Sphinx extension and a command-line tool that work together to generate a dynamic versions-menu similar to that on RTD pages.

The different “Versions” derive from the folder structure of the hosted documentation, e.g., for Github Pages, the folders in the root of the gh-pages branch. The docs-versions-menu command-line tool, running on the gh-pages branch or on the server hosting the documentation, collects the available versions based on the folders it sees.

The docs_versions_menu Sphinx extension, running during the Sphinx build process, adds Javascript to the documentation that will inject a menu to switch between the found versions. It can also show warnings for outdated or unreleased versions.

See the Docs-Versions-Menu documentation itself for a live example.

Development of Docs-Versions-Menu happens on Github. You can read the full documentation online.

Installation

To install the latest released version of docs-versions-menu, run:

pip install docs-versions-menu

Or, to install the latest development version of docs-versions-menu from Github:

pip install git+https://github.com/goerz/docs_versions_menu.git@master#egg=docs_versions_menu

The docs-versions-menu package can also be installed through conda, using the conda-forge channel. See the instructions in the Docs-Versions-Menu Feedstock.

Usage

Showing a versions-menu in your documentation requires two steps:

1. Add 'docs_versions_menu' to the list of extensions in your Sphinx conf.py.

   This adds Javascript to your rendered documentation that displays a dynamic versions-menu based on information in a versions.json file it expects to find in the webroot of the hosted documentation, e.g. the root of the gh-pages branch.

2. Set up the deployment of the documentation such that it runs the docs-versions-menu command in the webroot.

   The command creates the file versions.json that step 1 depends on by analyzing the folders it finds in the webroot.

   How to invoke docs-versions-menu this depends on the specifics of how the documentation is deployed:

   • For Github Actions deploying to Github Pages, check out the gh-pages branch, run docs-versions-menu, and commit and push the resulting files.

   • For Travis deploying to Github Pages with Doctr, tell doctr deploy to invoke the docs-versions-menu command:

     doctr deploy --command=docs-versions-menu --no-require-master --build-tags "$DEPLOY_DIR"

   • For deployments to a static web host, use ssh to run the docs-versions-menu command on the server

See the full documentation on Step 1 and Step 2 for details.

Default assumptions

For projects that follow standard best practices, you should not require any customization beyond the above two steps.

• Releases should be tagged as e.g. v0.1.0 and deployed to a folder of the same name. That is, a lower case letter v followed by a PEP 440-compatible version identifier.

• The master branch should be deployed to a folder master, respectively main to a folder main for projects that use “main” as the default branch name.

• Any other branch for which documentation is to be deployed should go in a folder matching the branch name.

Examples

The following projects use Docs-Versions-Menu, respectively its predecessor Doctr-Versions-Menu:

• Krotov

• caproto

• pcds-ci-helpers (an example of shared Travis CI configurations using docs-versions-menu)

• lcls-twincat-general (among many other PLC projects at the LCLS)

History

0.5.0-rc2 (2021-04-04)

• Improvements to the workflow and documentation.

• Update of conda-feedstock

Use this release to test migration from doctr-versions-menu to docs-versions-menu.

0.5.0-rc1 (2021-03-25)

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

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

• Dropped support for Python 3.5

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

• Replace the doctr-versions-menu package with docs-versions-menu in the project requirements and the environment files for continous integration.

• Replace calls to doctr-versions-menu with calls 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

• For any project using environment variables to configure the doctr-versions-menu utility, change the DOCTR_VERSIONS_MENU prefix to DOCS_VERSIONS_MENU

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

• Rename doctr_versions_menu_conf in your Sphinx conf.py file to docs_versions_menu_conf.

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)

• Initial release of doctr-versions-menu.