Create version selection menu as a configuration option

[barbaricyawps]

What's happening?

Apologies if you'd rather I open this as a GitHub discussion rather than an issue, but I'm trying to comply with your request to make this a "trackable task" in your project. Please advise me if you'd like this content in a different location.

User stories

As a documentation reader, I want to select different versions of the documentation so that I can read the documentation for an older product version or in my preferred language.

As a documentation provider, I want the ability to use the Furo theme on the hosting platform that best meets my project's needs and policies.

Motivation for this feature

Most projects have a need for version selection in their docs, specifically in two common scenarios:

• Language version selection - If a product's docs are localized, users need to be able to select the version of the product documentation for their preferred language.
• Product version selection - Users sometimes run older versions of the product for valid reasons. (For example, they might strategically delay upgrading to the latest version while waiting for the product to stabilize or to comply with company change management policies.) Those users need to be able to select the version of the documentation that matches the version of the product they are currently running in their environment.

If you want to use the Furo theme (like my team does!), you have the option of hosting your docs with Read the Docs (RTD), which provides product version selection. See Read the Docs - Versioned Documentation for more information. However, if documentation teams plan to host their docs on a different platform, they won't have the ability to do version selection. It's worth noting that for my team (the Salt Project), this is preventing us from adopting Furo as our documentation theme of choice.

To my knowledge, Read the Docs does not provide language version selection, but I could be wrong. FYI, my team doesn't currently localize our docs, but it is likely we will need to do so in the future. I've spoken to other large Python project owners who have this immediate need.

Feature requirements

• Provide a drop-down menu that lists older version of the product and/or available languages.
• Determine where the drop-down menus should appear in the Furo theme. Most likely the bottom left sidebar.
• Add a configuration option that allows users to turn version selectors on and off, since not all users will want this feature. (We'll also want to make sure that this plays well with Read the Docs since we don't want to break anyone's deployment.)

Helpful links, discussions, and prior art

I discussed this feature with @pradyunsg on the Write the Docs Slack earlier this year. He mentioned:

It's definitely technically possible. I haven't implemented something like that in Furo tho. It should be possible to implement something like this -- but I think the only Sphinx theme that has version support baked into it is https://pydata-sphinx-theme.readthedocs.io/en/latest/

In a separate conversation, @pradyunsg mentioned:

Some quick thoughts: I don't think there's any backend work necessary here but there's some Python code to be written to validate configuration stuff. The right place to put this design wise would be the bottom of the left sidebar (since that's the sidebar for the "site navigation"). It'd be reaaaally nice to also have this work seamlessly on RTD pages (or at least, be seamless when not specified) because I consider the users of RTD to be kinda important -- partly because I'm one of them, via pip.

The team that can do this work

I work with several developers as part of the Salt Project, a Python-based open source configuration management tool with 5,000 contributors. I've official approval from VMware (the company that currently sponsors this project) for some back-end and front-end developers on my team to build out the product version selector for Furo. It's possible this functionality could also be used for language selection as well. We're roughly looking at a May timeline to do the work and we hope to share our work upstream with the whole community.

Please let me know next steps and how I can connect you to my team if you'd like to have some exploratory conversations before May. I look forward to hearing what the community has to say about this proposal.

Reproducer

Not applicable to this task.

Expectation

Not applicable to this task.

Code of Conduct

• I agree to follow the Code of Conduct.

[raddessi]

Thank you for starting this FR! I have actually been wanting to bring this up myself and am willing to assist if needed. A few weeks ago I got this working with furo on a recent project by using the sphinx-multiversion plugin and replacing the ethical-ads section of the sidebar with the versions list.

I was planning on opening up an issue/PR here to create a new empty sidebar section that the users could replace for this purpose but I like your approach of setting this feature up properly much better.

Unfortunately(?) this implementation does require that each of the documentation versions to be included have to be built at the same time because the docs are monolithic - you can't build one version at a time and then show a dynamic list of versions based on what versions are deployed to your docs server, you just have to replace the entire docroot for that project. For me it's not a huge deal but there is no language selector either so I'm not sure how useful this would be as a jumping off point. I can provide info on how to duplicate this setup shortly in case it would help though.

Would you think that all of the selected versions should be built at once as a standalone bundle or should each version be able to be built independently and then cobbled together somehow? It's been a long time since I've used RTD because most of my work has been private, I'm not sure how they handle it.

[raddessi]

OK I posted an example of how to build furo's own docs with this method here for you to check out. The biggest immediate issue I can see is that I'm not sure if we can pass arguments to sphinx via multiversion which means the builds are not in dirhtml format :/ That problem was going to be next on my list to dig in to.

[pradyunsg]

Apologies if you'd rather I open this as a GitHub discussion rather than an issue, but I'm trying to comply with your request to make this a "trackable task" in your project. Please advise me if you'd like this content in a different location.

No need to apologize -- this is definitionally a "trackable task", which is why I asked you to file it. :)

I got this working with furo on a recent project by using the sphinx-multiversion plugin

That's neat! Using an existing plugin is a good idea. Doing this using VCS as a source of truth is a neat idea. I'll let others chip in whether that'll work for them. That said, I don't think a dump of all the links to all the versions as-is, is a particularly nice UI. :)

One thing that works nicely with this idea, is that the implementation complexity of handling such systems can be moved into that plugin (or a different one, that behaves differently but provides the same HTML template variables). That's something that I like, because it means that Furo doesn't need to provide any direct coonfiguration knobs to control what "versions" in your documentation look like, deferring that to the Sphinx extension that's gathering the version information.

Add a configuration option that allows users to turn version selectors on and off, since not all users will want this feature.

I don't think we should add a configuration option for "off/on" -- I'd strongly prefer that this behave something like "oh, you've provided version information, lemme include that in the pages". In other words, users who use whatever mechanism we end up with, for providing multiple versions, should not need to also set something like furo_allow_multiple_versions = True or whatever.

[pradyunsg]

Determine where the drop-down menus should appear in the Furo theme. Most likely the bottom left sidebar.

1e38428 puts the Read the Docs embed in that location as well!

[pradyunsg]

FWIW, here's where you can see the "new" Read the Docs variant selector styling: https://furo.readthedocs.io/ (scroll past the announcement)

I think the thing to do would be to update src/furo/theme/furo/sidebar/variant-selector.html to also support whatever mechanism we end up adopting. That mechanism is still TBD, as far as I can tell.

[raddessi]

Yeah, I would love it we could have a layout similar to the latest RTD theme. I'm not at all good at UX design, I just wanted to show a simple functional example of multiversion integration.

[barbaricyawps]

Thanks @pradyunsg and @raddessi for your great comments so far! I'm definitely following this thread and will share it with this team. Keep the discussion going!

[pradyunsg]

What's the next steps here, who's doing what? :)

If just baking in support for sphinx-multiversion will make people happy, then this is a fairly simple change:

• change variant-selector.html to use the context variables injected by sphinx-multiversion when not building on RTD.
• stylise that so that it looks and behaves somewhat similarly to RTD's embed.

Another thing I like about this is that if people want to have a different strategy for providing these context variables to Furo, they're welcome to write their own logic for generating those context variables in a Sphinx extension; allowing for custom workflows on that front as well.

[barbaricyawps]

The engineers from our team that are likely to do this work will be s0undt3ch and/or waynew, but be aware we won't likely do this work until May. That's the timing I've gotten approval for. Would you like me to arrange a meeting at all, @pradyunsg ? What would be best for us to collaborate?

[raddessi]

Fwiw, I will send up a PR up to the sphinx-multiversion project soon to add support for dirhtml builds. I do like the end-user flexibility that using multiversion allows.

I'm not trying to imply that multiversion has been chosen as the route to go down, I just want to get the feature added ahead of time in case we do use it for this.

[Rjvs]

@pradyunsg building in support for sphinx-multiversion would certainly work for me. It would also be nice if there was built-in support for admonitions/notices that the currently-viewed version is not released or not current (like on RTD, e.g. https://sphinx-rtd-theme.readthedocs.io/en/1.0.0rc1/ ).