Package: docs-versions-menu
Docs-Versions-MenuA versions-menu forSphinx-based documentation.Historically, many open source projects have hosted their documentation onRead the Docs(RTD). However, RTD has a fixedbuild processthat is essentially limited to just runningSphinx. 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 toGithub Pagesor any other static site hosting. There are no restrictions on the build process: it may involvemake,tox,latex, or any number of custom scripts to augmentSphinx.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. Itprovides 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., forGithub Pages, the folders in the root of thegh-pagesbranch. Thedocs-versions-menucommand-line tool, running on thegh-pagesbranch or on the server hosting the documentation, collects the available versions based on the folders it sees.Thedocs_versions_menuSphinx 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 alive example.Development of Docs-Versions-Menu happens onGithub.
You can read the full documentationonline.InstallationTo install the latest released version ofdocs-versions-menu, run:pipinstalldocs-versions-menuOr, to install the latest development version ofdocs-versions-menufromGithub:pipinstallgit+https://github.com/goerz/docs_versions_menu.git@master#egg=docs_versions_menuThedocs-versions-menupackage can also be installed throughconda, using
theconda-forgechannel. See theinstructions in the Docs-Versions-Menu
Feedstock.UsageShowing a versions-menu in your documentation requires two steps:Add'docs_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 webroot of the hosted documentation, e.g. the root of thegh-pagesbranch.Set up the deployment of the documentation such that it runs thedocs-versions-menucommand in the webroot.The command creates the fileversions.jsonthat step 1 depends on by analyzing the folders it finds in the webroot.How to invokedocs-versions-menudepends on the specifics of how the documentation is deployed:ForGithub Actionsdeploying toGithub Pages, check out thegh-pagesbranch, rundocs-versions-menu, and commit and push the resulting files.
See theworkflow filefor Docs-Versions-Menu’s documentation.ForTravisdeploying toGithub PageswithDoctr, telldoctr deployto invoke thedocs-versions-menucommand:doctrdeploy--command=docs-versions-menu--no-require-master--build-tags"$DEPLOY_DIR"For deployments to a static web host, usesshto run thedocs-versions-menucommand on the serverSee thefull documentationon Step 1 and Step 2 for details.Default assumptionsFor 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.0and deployed to a folder of the
same name. That is, a lower case lettervfollowed by aPEP 440-compatible
version identifier.Themasterbranch should be deployed to a foldermaster, respectivelymainto a foldermainfor projects thatuse “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.ExamplesThe following projects useDocs-Versions-Menu, respectivelyits predecessor Doctr-Versions-Menu:Krotovcaprotopcds-ci-helpers(an example of shared Travis CI configurations using docs-versions-menu)lcls-twincat-general(among many other PLC projects at the LCLS)History0.5.2 (2023-04-19)Compatibility withpackaging >= 22.0(#27,#32)0.5.1 (2023-01-25)Pinpackagingdependency to< 22.0(#27,#28)0.5.0 (2022-11-17)Renamed project todocs-versions-menu(#13)Changed: Removed support for a config file (#9)Dropped support for Python 3.5 and Python 3.6Added support for Python 3.10 and 3.11Improvements to the workflow and documentation.Update ofconda-feedstockMigration fromdoctr-versions-menuThedoctr-versions-menupackage was renamed todocs-versions-menuto reflect thatTravisand thusDoctrisno longer a viable option to deploy documentation. Switching fromdoctr-versions-menutodocs-versions-menurequires the following steps:Consider switching fromTravistoGithub ActionsUpdate your Sphinx configuration (conf.py):Rename thedoctr_versions_menu_confdictionary of settings todocs_versions_menu_conf.Change the name of thedoctr_versions_menuextension in theextensionslist todocs_versions_menu.If using a customdoctr-versions-menu.js_ttemplate, rename the file todocs-versions-menu.js_tUpdate your continuous-integration setup:Replace thedoctr-versions-menupackage withdocs-versions-menuin the project requirements (setup.py/setup.cfg)Replace the installation of thedoctr-versions-menupackage withdocs-versions-menuin your CI script or environment filesReplace calls to thedoctr-versions-menuexecutable with calls todocs-versions-menuIf using environment variables for configuration, change theDOCTR_VERSIONS_MENUprefix toDOCS_VERSIONS_MENUFor any project using adoctr-versions-menu.conffile in thegh-pagesroot, set up equivalentDOCS_VERSIONS_MENU_*environment variablesTo ease migration, the newdocs-versions-menuwill still processdoctr_versions_menu_conf,DOCTR_VERSIONS_MENUenvironment variables, and adoctr-versions-menu.js_ttemplate, 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 namedoctr-versions-menu.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)Note: this release was under the project namedoctr-versions-menu.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)Note: this release was under the project namedoctr-versions-menu.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)Note: this release was under the project namedoctr-versions-menu.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 ofdoctr-versions-menu.