Docs: drop-down menu for same-page version switching

[sadielbartholomew]

We've noted we'd like a collapsible drop-down menu (in the sidebar, for example) for selecting and changing the version of the documentation being shown, where equivalent pages are mapped across versions, rather than pages at specific versions needing to be accessed via their index pages as a starting point.

Such a menu is provided for any docs hosted with ReadTheDocs (at least covering limited aliased versions e.g. 'latest', 'stable'), but for self-hosted docs not using the theme sphinx_rtd_theme, a bit of manual configuration & templating seems to be required. It's definitely possible without too much difficulty or code, as I have seen from some examples (see some listed below), but it is not easy to trace the parts of the docs source and config that result in the versioning in each case.

Note that the completion of this can and should go hand-in-hand with addressing #28 (once a structure to process versions is in, it becomes trivial to add some new text to all pages of a certain version, by templating, and the versioning extensions below provide this as a configuration option) and since it relates to documentation customisation, it would be good to tackle #50 simultaneously also.

References

Some helpful resources I've found after a little investigation:

• The pytest docs: see menu at bottom right which covers about 100 versions (note the theme looks like alabaster but is in fact a different one, with version menu processing seemingly coded up here).
• A useful comment with code snippets illustrating how they have achieved something similar (for a different theme, but probably could work for alabaster with or without some modification): Add version dropdown (for other versions of the docs) pydata/pydata-sphinx-theme#23 (comment)
• some Sphinx extensions that might be able to help, but might be excessive depending on what can achieve the basic goal:
  • sphinx-multiversion
  • perhaps sphinxcontrib-versioning or sphinx-versions though ideally not since they look like they might be going stale, with no commits for 1+ year.