doctr-versions-menu 0.4.1

Sphinx extension and command to add a versions menu to Doctr-deployed documentation

Doctr Versions Menu

Sphinx extension and command to add a versions menu to Doctr-deployed documentation.

Doctr is a tool that deploys Sphinx documentation from Travis CI to Github Pages. It is an alternative to the popular Read the Docs (RTD). Compared to RTD, Doctr gives full control over the documentation build process. However, Doctr out of the box does not support documentation for multiple versions of a package at the same time (unlike RTD).

The doctr-versions-menu package 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:

It also injects warnings for outdated or unreleased versions.

See the doctr-versions-menu documentation itself for a live example.

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

⚠️ As of December 2020, Travis no longer provides free services to open source projects. See Deployment with Github Actions for a workaround.

Installation

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

pip install doctr-versions-menu

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

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

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

In practice, you probably only have to install the doctr-versions-menu package on Travis, for generating and deploying the documentation; or, e.g., in a local tox environment for generating documentation locally during development.

Usage

Showing a versions menu in your documentation requires two steps:

1. Add 'doctr_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 root for your gh-pages branch.

2. Call the doctr-versions-menu command as part of doctr deploy (in .travis.yml).

   For example,

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

   This causes doctr-versions-menu to be executed in the root of the gh-pages branch. The script examines the folders that exist there, and generates the versions.json file that step 1 relies on.

See the full documentation on Step 1 and Step 2 for details. However, for projects that follow normal best practices, you should not require any customization beyond the above two steps.

Examples

The following projects use doctr-versions-menu:

• Krotov

• caproto

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

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

History

0.4.1 (2021-03-18)

• 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)

• 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)

• 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)

• 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