Create version selection menu as a configuration option

@pradyunsg

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.

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.

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.

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.

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!

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.

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.

@pradyunsg

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!

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.

@pradyunsg

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?

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.

@pradyunsg

@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/ ).

Those are injected by ReadTheDocs -- and I'm pretty sure you can use something like https://pypi.org/project/sphinx-version-warning/ for that stuff.

hi, I appreciate your work on this theme. I provide the user manual for Zrythm in multiple languages and it would be very useful to have a language switcher somewhere as well as mentioned in the OP

I have also "hacked together" a version switcher in Furo by making a _templates/versions.html and adding

html_context = {
    'help_versions': [
        'dev', '1.0', '1.1', '1.2','1.3', ], }

to my conf.py, but it hard-codes too many assumptions about the final docs page. I'm curious if this issue will be able to solve my needs

Demo: https://irssi.org/documentation/help/connect

@waynew

@waynew What's the next steps here? Do you want to take this forward, should I let this linger for a bit longer or are you OK with letting someone else pick this up and take it forward?

This is in a bit of a limbo at the moment and it would be good to resolve that. :)

@pradyunsg

@pradyunsg , sorry we're moving a little slowly, but we're working with a front-end developer to make the style improvements. After that work is done, I think we'll be ready to go, right?

Yup, sounds great to me! Thanks for the super quick response! ^.^

@pradyunsg

@pradyunsg , just FYI, are you aware that Wayne's PR for this has been in and ready to review for a little while now? Anything we can do to help get it merged in? #500

I am, yes. I've had limited OSS time thanks to life happening, but I should be able to make time to look at that PR (and Furo more broadly) this weekend. :)

@waynew

FWIW, that's for the nudge on this -- I'd missed the first one from @waynew (sorry!).

no worries... It happens to me all the time 😅

@pradyunsg

We totally get it, so don't stress about it @pradyunsg . It's not crucial for us that it get merged in since we can apply the change locally if we need. We just wanted to share it more broadly with the community if it helps anyone in a similar boat. Thanks for being so great to work with! 😄

Hello guys! Just read the whole conversation. I am wondering if there's any update on the multi language selector for furo

@Rage997

@Rage997 , I'd recommend checking out the open PR, which includes a link in the comments to our doc site where you can see it in action and see if it might fit your needs: #500

Is there a plan for adding the version selector code to furo? Anything I could help with?

Hi, is there any plan for this? Supporting multiple version builds using furo would be very useful!

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

Hi 👋🏼, I just wanted to chime in here to let you know that Read the Docs does support version and language selectors (https://docs.readthedocs.io/en/stable/localization.html). Godot is a good example of a large multi-language multi-version project hosted on Read the Docs. Take a look at their docs at https://docs.godotengine.org/en/stable/

By the way, I work at Read the Docs, so feel free to open an issue/contact support there if you are still considering hosting the documentation there. I'm happy to help you with that process.

Adding my voice to the feature request to add version support to the Furo Sphinx Theme. Highly requested feature here too that intersects with key business outcomes, including better expectation setting for server supportability and elevating customer trust on product release lifecycles.

Just wanted to add my voice here too. I'm probably going to move to the PyData theme to get the version support. But I do wish I could keep the Furo theme as I find it much more pretty. I do understand that available time to work on open source projects is limited though!

Navigation Menu

Repository navigation

Create version selection menu as a configuration option #372

What's happening?

User stories

Motivation for this feature

Feature requirements

Helpful links, discussions, and prior art

The team that can do this work

Reproducer

Expectation

Code of Conduct

14 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Create version selection menu as a configuration option #372

Description

What's happening?

User stories

Motivation for this feature

Feature requirements

Helpful links, discussions, and prior art

The team that can do this work

Reproducer

Expectation

Code of Conduct

Activity

raddessi commented on Feb 12, 2022

raddessi commented on Feb 12, 2022

pradyunsg commented on Feb 13, 2022

pradyunsg commented on Feb 13, 2022

pradyunsg commented on Feb 13, 2022

raddessi commented on Feb 14, 2022

barbaricyawps commented on Feb 14, 2022

pradyunsg commented on Feb 27, 2022

barbaricyawps commented on Feb 27, 2022

raddessi commented on Feb 27, 2022

Rjvs commented on Mar 18, 2022

pradyunsg commented on Mar 18, 2022

alex-tee commented on Apr 6, 2022

ailin-nemui commented on May 5, 2022

14 remaining items

pradyunsg commented on Sep 29, 2022

barbaricyawps commented on Sep 29, 2022

pradyunsg commented on Sep 29, 2022

barbaricyawps commented on Nov 16, 2022

pradyunsg commented on Nov 16, 2022

pradyunsg commented on Nov 16, 2022

waynew commented on Nov 16, 2022

barbaricyawps commented on Nov 16, 2022

Rage997 commented on Feb 24, 2023

barbaricyawps commented on Feb 24, 2023

raddessi commented on Feb 5, 2024

amrit110 commented on May 22, 2024

humitos commented on May 23, 2024

cwarnermm commented on Sep 13, 2024

golmschenk commented on Sep 14, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions