Package: doctr-versions-menu
Doctr Versions MenuSphinxextension and command to add a versions menu toDoctr-deployed documentation.Doctris a tool that deploysSphinxdocumentation fromTravis CItoGithub Pages. It is an alternative to the popularRead 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).Thedoctr-versions-menupackage 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 thedoctr-versions-menudocumentation itself for alive example.Development of Doctr Versions Menu happens onGithub.
You can read the full documentationonline.⚠️As of December 2020, Travis no longer provides free services to open source projects.SeeDeployment with Github Actionsfor a workaround.InstallationTo install the latest released version ofdoctr-versions-menu, run:pipinstalldoctr-versions-menuOr, to install the latest development version ofdoctr-versions-menufromGithub:pipinstallgit+https://github.com/goerz/doctr_versions_menu.git@master#egg=doctr_versions_menuThedoctr-versions-menupackage can also be installed throughconda, using
theconda-forgechannel. See theinstructions in the Doctr Versions Menu
Feedstock.In practice, you probably only have to install thedoctr-versions-menupackage onTravis, for generating and deploying the documentation; or, e.g.,
in a localtoxenvironment for generating documentation locally during
development.UsageShowing a versions menu in your documentation requires two steps:Add'doctr_versions_menu'to the list of extensions in your Sphinxconf.py.This adds javascript to your rendered documentation that displays a dynamic versions menu based on information in aversions.jsonfile it expects to find in the root for yourgh-pagesbranch.Call thedoctr-versions-menucommand as part ofdoctr deploy(in.travis.yml).For example,doctrdeploy--command=doctr-versions-menu--no-require-master--build-tags"$DEPLOY_DIR"This causesdoctr-versions-menuto be executed in the root of thegh-pagesbranch. The script examines the folders that exist there, and generates theversions.jsonfile that step 1 relies on.See thefull documentationon 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.ExamplesThe following projects usedoctr-versions-menu:Krotovcaprotopcds-ci-helpers(an example of shared Travis CI configurations using doctr-versions-menu)lcls-twincat-general(among many other PLC projects at the LCLS)History0.4.1 (2021-03-18)Fixed: Thedoctr-versions-menuexectuable no longer fails when run outside of a git repository (#15, thanks toAlexander Blech)Fixed: Customdoctr-versions-menu.js_ttemplate 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 inconf.py(settingmenu_title).Added:--default-branchoption,<default-branch>group for folder specifications, anddefault-branchfield inversions.json(#12)Changed: The default--versionsnow uses<default-branch>, automatically picking up on either “master” or “main” as the default branch (#12)Changed: The default template forindex.htmlnow automatically forwards to the default-branch (based on the--default-branchoption, instead of just “master”), or the first available branch if there is no released version (#12)This release addresses two major compatibility issues:BothgitandGithubhave 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.As of December 2020, Travis CI hasstopped their support for open source. Consequently,Doctrcan no longer be used to deploy documentation at no cost. This release adds rudimentary support for deploying the documenation withGithub Actionsinstead of Doctr, seeDeployment with Github Actions.0.3.0 (2020-08-03)Added:--no-downloads-fileoption,downloads_file = Falsein config. (#4, thanks toTyler Pennebaker)Fixed:versions.pyongh-pagesbranch was not being committed (#5)Fixed: Compatibility with anypyparsingversion>= 2.0.2(#8, thanks toHugo Slepicka)Added: Thedoctr-versions-menuexecutable can now be configured through environment variables. This allows to keep configuration on the source branch, in the.travis.ymlfile (#6, thanks toTyler Pennebaker)The Doctr Versions Menu package can now be installed viaconda(thanks toHugo Slepicka)0.2.0 (2020-03-14)Added:--versionsoption for customizing which folders appear in the versions menu and in which order.Added:--labeloption for customizing the labels appearing the versions menuAdded:--warningoption for customizing on which folders specific warnings are displayedAdded:--latestoption for configuring which folder is the “latest stable release”Added: Write a scriptversions.pyto the root of thegh-pagesbranch (--write-versions-pyoption)Changed: unreleased and pre-released versions now show different warnings by defaultChanged:index.htmltemplate is now rendered with fullversion_dataChanged: development/pre-release versions now longer have the “dev” suffix in the versions menu by defaultChanged: 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 ofversions.jsonRemoved:--default-branchoption. This is replaced by the new--latestoption and enhanced template rendering of theindex.htmlRemoved:--suffix-unreleasedoption. This can now be achieved via the--labeloptionThis is a major release that breaks backwards compatibility.Specifically, due to the changes inversions.json, when upgrading from older versions, it
may be necessary to replacedoctr-versions-menu.jsfiles in existing
folders in a project’sgh-pagesbranch.0.1.0 (2020-01-11)Initial release