How it works

The theme comes in two parts:

A commandline script that generates a versions.txt file at documentation build time
A bit of javascript that populates the versions section of the sidebar at runtime

Commandline script

This works by writing a versions.txt file alongside the build documentation directories that are pushed to the gh-pages branch. These are ordered:

main or master branch
tags in descending order
other branches

This generation should be run at CI time using something like this:

https://github.com/DiamondLightSource/sphinx_rtd_theme_github_versions/blob/master/.github/workflows/docs.yml

Javascript population

This works by fetching ../versions.txt and populating an Other Versions section of the side-bar with the contents. If the fetch fails the that section is hidden.