Skip to main content

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

Project description

Doctr Versions Menu

Source code on Github Documentation doctr-versions-menu on the Python Package Index Travis Continuous Integration AppVeyor Continuous Integration Coveralls MIT License

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:

Doctr Versions Menu Screenshot

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.

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

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.

History

0.1.0 (2020-01-11)

  • Initial release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for doctr-versions-menu, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size doctr_versions_menu-0.1.0-py2.py3-none-any.whl (524.1 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size doctr_versions_menu-0.1.0.tar.gz (741.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page