ENH: Add version switcher dropdown menu

[greglucas]

This is the start of adding a version dropdown selector as discussed in #23. I don't have a lot of time to work on this now, so if someone wants to borrow any of this or extend it, please feel free to.

I'm not entirely clear what the end goal is here. From what I can see, most people either roll their own javascript that does some form of regular expression parsing of the version numbers or use the built-in readthedocs version switcher that they provide (this hosted theme site already uses that). Do we want to force people into a standard within this theme, or do we want to be really flexible and allow many different url formats, version formats, etc...?

Here is a list of what this has so far:

• Added a new theme option "version_switcher" that takes a dictionary of values to set up the version switching parameters
• Added HTML for the dropdown buttons
• Added javascript to handle the regular expression replacements of the page href

The HTML buttons have a good look/feel, but the javascript needs some work. I also don't know how to pass sphinx theme options into the javascript utility functions, is there a good way to do that? This would make it easy to allow each project to define their own regular expressions for version finding without needing to directly modify the javascript included here.

CPython also has their versions hardcoded in the included js, not a separate versions.json file.
https://github.com/python/cpython/blob/master/Doc/tools/static/switchers.js
They also have a language selector that would be a good extension in a separate PR.

[cheekyshibe]

It's a really useful feature. 😄 What's your strategy to archive the old version documents' website if I want to keep it showing the latest version list in dropdown menu. For example, I hope users can click the menu in archived v1.0 website then it shows v1.1 / v1.2 / latest. How about making it always use the switcher in the latest version? (Any other ideas?)

[greglucas]

Per this comment, #23 (comment), it seems like a common approach is to put a versions.json or similar file at the root of the documentation site that can be kept up to date and that all versions can reference. I took that approach here and provided a way to specify the root url and name of that json file.

I haven't looked at this in quite a while though, so I may be out of the loop. Not sure if this is still desired to be a part of the theme, or if sphinx-multiversion or some other tool would be better to recommend?

[damianavila]

@greglucas, there are currently two other more mature PRs superseding this one, so I am going to close this PR now.
Thanks for being the first one to submit a possible implementation for #23.
We really appreciate your contribution here and we hope to see you again submitting new PRs 😉 !