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

[pradyunsg]

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.

[alex-tee]

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

[ailin-nemui]

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

[pradyunsg]

Would you like me to arrange a meeting at all, @pradyunsg?

I'm ambivalent. I can see the value in that, but I also have limited availability now (I'm on vacation for a few more weeks).

What would be best for us to collaborate?

Comments on this issue, for now.

[barbaricyawps]

By the way, in terms of a status update on our end, my team has had a lot of delays and I'm not sure when they're going to get to developing this feature. I'm currently predicting it will be July, but I'll let you know if that changes.

[raddessi]

Sadly it appears that https://github.com/Holzhaus/sphinx-multiversion may be unmaintained now.

[BurningEnlightenment]

Sadly it appears that https://github.com/Holzhaus/sphinx-multiversion may be unmaintained now.

I proposed some organizational changes to improve the situation (s. Holzhaus/sphinx-multiversion#88), but there hasn't been a response in 11 days. I'm not very familiar with python, so I can't judge whether forking sphinx-multiversion would be better than starting from scratch.

[pradyunsg]

@barbaricyawps Hiya! Let me know if y'all have had time budgeted toward this, for this month. :)

[barbaricyawps]

@pradyunsg , I confirmed with my engineering team recently whether they would have time for this, so we should be good. I think we (finally) go into code freeze this week and so we'll have some cycles available to work on it. Thanks for checking in!

[waynew]

Hey friends! Just starting to really dig into this. I'm pretty confident from looking at it that sphinx-multiversion is (currently) unmaintained -- the last change to the repo was 14 months ago and most changes were 2+ years. I think the last release was in 2020.

That being said, that's not actually a huge blocker here - as @pradyunsg pointed out earlier, as long as we just check for the presence of some variables that mean we have some versions, we should be able to go ahead and use those variables to present the version selector (and the "hey these aren't the current docs!" warning)

I don't think that I'll make it to the point today where I've got any kind of PoC -- I think some of these other efforts are heading down the right track so I'll probably just pick those up and start with the absolutely horrible dump of all the versions. Styling should just be a matter of CSS at this point in Internet history.

I'll keep this thread posted with any updates 👍

[waynew]

Ah, okay super interesting! Looks like sphinx-multiversion actually takes care of rebuilding old docs versions, which is a question that we had from our internal discussion.

I have a bit better handle on the operation of things now and the pieces are falling into place. I think I'm a pretty huge fan of just checking for the HTML context variable sphinx-multiversion provides. As long as they quack like a multiversion variable, we should be 💯 🆗 here.

[waynew]

Okay, so I have a very basic PoC that "works" for definitely-not-good-looking values of "works". In other words, if you're using lynx it's fine, but anything like Firefox, Chrome, or Safari will just be 🤢

But that's okay because style is something that we can overcome 😂

To check it out:

mkdir -p /tmp/test-stuff
cd /tmp/test-stuff
git clone -o wayne https://github.com/waynew/furo.git
git clone -o wayne https://github.com/waynew/salt-ext-modules-vmware.git
python -m venv env --prompt review-furo-version
source env/bin/activate
python -m pip install --upgrade pip
cd furo
git checkout wayne/version-selector
python -m pip install -e .
cd ../salt-ext-modules-vmware
git checkout -b test/version-docs wayne/test/version-docs
python -m pip install -e .\[docs\]
python -m pip install sphinx-multiversion
sphinx-multiversion docs docs/_build/html && python -m webbrowser docs/_build/html/main/index.html

At the end of that you should have your web browser open with something that looks like this in your sidebar:

@pradyunsg if you'd like/want to offer some feedback I can go ahead and open a draft PR -- otherwise I'm going to hold off until I have it at least looking decent.

@barbaricyawps One current limitation of sphinx-multiversion is that it doesn't offer a very elegant way to just list the most recent versions... they're blocked out/selected via regex (fun!), so it is possible, just... interesting.

I also want to take another/closer look at https://pypi.org/project/sphinx-version-warning/ to see if it's pretty easy to use that capability for Salt's docs, or if we'd need to take a different approach 👍

[pradyunsg]

Neat -- I just tried building this and, although the sphinx-multiversion run failed, I managed to hack around some quirks around the C/C++ dependencies on M1, and get the build working.

I'm happy to wait until you have the styling figured out. :)

[Yura52]

After skimming through the discussion, I am a bit confused, why json-based solutions are not considered such as the ones in PyData and Sphinx Material themes? What I like about them is the total transparency in terms of what is going on, no reliance on VCS or any other hidden state. Also, wouldn't it be easier in terms of implementation for Furo?

I have read this comment, but I do not completely understand it. The "automatic" scenario is already implemented by the RTD. Users who prefer other hosting platforms are likely to be advanced enough to deal with a json-based approach :)

P.S. I have just moved to Furo from Sphinx-Material (which has a convenient version dropdown) and I want to share a smart hack for version switching (see the left sidebar):

https://yura52.github.io/delu/stable/index.html

Credits go to PyTorch 😄 Jokes aside, would be super cool to have a native solution!

[waynew]

FWIW, I came down with COVID earlier this week so I haven't made any progress here - feeling a bit better, hope to be able to pick this back up next week.

@Yura52 in regards to JSON-based solutions, the guiding ideas that simple is good enough, and more than sufficient; and more stuff is not more good are the ideas that I'm trying to follow. JSON based solutions would require a non-zero amount of Javascript to process. At least when it comes to my goals that's less ideal - it will fail on older browsers or when folks disable Javascript. It also means that Furo has to maintain some logic on how, exactly, to generate version information (probably).

I could be misunderstanding, but letting Sphinx tell us what the versions are, and relying on CSS to provide some fancier behaviors for the browsers that support it feels like the right approach to me.

[pradyunsg]

Hope you get better soon @waynew with no lingering symptoms. Please don't feel any pressure from my end to do this soon. :)

---

In addition to what @waynew says... see also (from later in the thread, relative to the comment you linked to):

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.

Pragmatically, it means that someone else can write the code to take a JSON blurb (like pydata or material do), and expose that to the theme as template variables.¹ You can't do it the other way around. This approach is not coupling your version management to the theme's implementation and is strictly more flexible.

Also, wouldn't it be easier in terms of implementation for Furo?

Well... it'll be more complexity, in terms of needing to cater to more usecases "natively". One could argue that it'll be less code overall "in the ecosystem" but... if that were a goal, Furo wouldn't exist -- I would've instead finished https://github.com/pradyun/materialism, or https://github.com/pradyun/sphinx-mkdocs-theme, or contributed to sphinx-rtd-theme with a knob to add a right sidebar and collapsible left sidebar navigation, or something like that.

---

Finally, this is the first user workflow for Furo that I don't have any use for personally -- all my OSS projects are on RTD.

I won't have good/clear judgement criteria for what are reasonable workflows/approaches for this. In more ways than one, I think it'd be best to not have logic for versioning functionality in Furo. Any feature development/effort I put toward that will have to come out of my empathy for primarily-institutional users, of which I only have a limited amount. Spending that "empathy budget" on pip/Python Packaging stuff seems like a more worthwhile investment for everyone involved. :)

Footnotes

1. It'll be like, 50 lines of Python. You can probably figure out most of it from looking at Furo's __init__.py file, and the handling of page-context + configuration variables. ↩

[Yura52]

I see, thank you very much for explaining this.

[pradyunsg]

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

[barbaricyawps]

@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?

[pradyunsg]

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

[barbaricyawps]

@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

[pradyunsg]

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. :)

[pradyunsg]

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

[waynew]

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

[barbaricyawps]

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! 😄

[Rage997]

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

[barbaricyawps]

@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

[raddessi]

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