Integration with ReadtheDocs' new addons based version switcher (and other addons)

[Cadair]

disclaimer: I had a search around the repo for things looking similar to this, hope I am not missing anything

---

RTD have added a new "addons" based version switcher that doesn't go into the sidebar of the theme like the old one did, does anyone have any context or starting points for getting their new addons based version switcher integrated into the theme?

Also there are other addons, but maybe the version warning already is themed?

[nabobalis]

More context about the addons: https://about.readthedocs.com/blog/2024/07/addons-by-default/

[trallard]

Thank you for flagging this; I have seen mentions around but have not looked deeply into it.

Also there are other addons, but maybe the version warning already is themed?

We have our own version warning in PST but will have a look nonetheless

[drammock]

related: #1398 (which was capturing and re-styling the old injected RTD switcher, but never quite got over the finish line). That can maybe serve as a starting point for the styling, though it may also be stale enough to not bother with.

crossref also to readthedocs/readthedocs.org#11474 (attn @trallard I'd been meaning to ping you there as a heads up)

@Cadair IIUC, the way of integrating the new addon into this theme is to

listen to the readthedocs-addons-data-ready JavaScript event to get all the Read the Docs data in a JSON-like1 object and generate the flyout as you prefer

(source: readthedocs/readthedocs.org#11474 (comment)). In other words, I think we need to write some JavaScript to:

1. listen for the RTD addons event, and if detected,
2. construct a (themed) version switcher from the RTD JSON data instead of building our native version switcher, and
3. add it to the page DOM

It's also worth looking at whether we want to change our native JSON structure to something more similar to the new RTD JSON structure (not sure how (dis)similar they are, I haven't checked yet). It would mean code churn for our users, but it might avoid some nasty near-duplicated code. Or we could simply mutate our native JSON at load time to mimic theirs, that might be the least painful route.

[Cadair]

I don't mind having a shot at this in principal, but I don't know when I will find the time, but if I do I will make sure to post here.

Thanks for all the info ❤️

[humitos]

Hi all 👋🏼 . I'm one of the authors behind the new Read the Docs Addons and the deprecation of the Sphinx context automatically injected. I just wanted to comment here in case you have doubts/questions. I'm happy to help with this transition to be as smooth as possible, so feel free to ask me any questions you may have regarding this.

[trallard]

Hey folks, thanks for the ping!
I have had this in my radar but have been too swamped to figure out what exactly needs doing for PST unless @drammock has already started doing some of this.

If not, I will try and carve some time to understand the implications and open a meta issue to track any actions needed on our end.
I am sure I will be pinging @humitos as I figure things out.
Also IIRC there was already some work on the Python docs (or dev guide?) by @humitos in line with this change so will have a look too.

[drammock]

I have had this in my radar but have been too swamped to figure out what exactly needs doing for PST unless @drammock has already started doing some of this.

I've not started in on this yet.

[Cadair]

I have just swung back to looking at this. It seems that the version warning injected by RTD isn't themed by pydata-sphinx-theme. It would obviously be good if we could make the RTD version warning show in the same style as the native pydata one.