Support multiple docset versions with something like a "versions" dropdown menu

[ScriptAutomate]

Is your feature request related to a problem? Please describe.

When multiple versions of a docset exists, due to new releases over time, if the docs aren't making use of a hosting site like ReadTheDocs, then multiple versions can't be supported.

Describe the solution you'd like

A different Sphinx theme, sphinx-material, approaches this with an optional dropdown menu seen used on the demonstration site:

• https://bashtage.github.io/sphinx-material/
  • Documentation on how the dropdown can be configured: https://bashtage.github.io/sphinx-material/customization.html#version-dropdown

It allows for multiple versions of the documentation to exist on the site under different sub-paths. This allows people to link directly to a target version when sharing links, in the event that functionality/documentation changes in a future release.

Describe alternatives you've considered

I'm not sure about how other themes may have implemented this kind of support, and what would be the best approach for furo to place it in the page: perhaps beneath the search bar? Maybe displayed with a different aesthetic that better blends within the theme?

[pradyunsg]

Thanks for filing this issue!

I don't think this needs to be done at the theme level. It's already available via ReadTheDocs, and I'd prefer folks either replicate their approach or use ReadTheDocs directly. 🤷🏻‍♂️

See https://pip.pypa.io/en/stable for an example of how that works, where you can select the other available versions using the JS-based dropdown that shows up in the bottom right.

[ScriptAutomate]

Ah, that makes sense, with what is seen here:

• https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/sidebar/rtd-versions.html

So if someone wanted to display options for multiple hosted versions, on a site hosted elsewhere outside of RTD, they could perhaps create a custom partial for that situation. I may submit a PR in the future for an optional versions menu for those hosting the theme elsewhere.

[pradyunsg]

TBH, I don't think that custom logic needs to live in Furo directly though. It's certainly possible to add custom elements in Furo's sidebar -- I wrote an entire section in the documentation, establishing expectations and explaining how to do that. IMO possible to make this reusable without having it be a part of Furo, and I'm happy to call out examples of customised sidebars with additional functionality is done on that page.

My bias here is straightforward: I'd like to keep things at a minimum here because I only have so much time. The less that this theme provides/does directly, the easier it is for me to "keep the lights on" for it. :)

---

What ReadTheDocs does is that they have an extension that adds the relevant JS/CSS/HTML for the version selector they provide. I'm not a 100% sure if their logic is reusable as-is, but I do think the approach to take would be to make something that's not tied to Furo directly, but that works well with it (see https://github.com/pradyunsg/sphinx-inline-tabs for example).

[ScriptAutomate]

All very good points. I'll close out the issue with that in mind. Thank you for making this so extensible, and for the great documentation so far!