DOC: RTD version switcher missing from main page using pydata-sphinx-theme

[pllim]

As @stefanv pointed out, RTD version switcher cannot be accessed from https://astropy.readthedocs.io/en/latest because it appears on the bottom of left navbar and that navbar is not shown in the main page. Not sure what is the best solution for this. Hopefully @drammock can advise. 🙏

AFAIK, this switcher is injected by RTD because I don't remember ever setting it up.

[drammock]

good news and bad news: it's a known bug (pydata/pydata-sphinx-theme#1092) and we've been working on it (pydata/pydata-sphinx-theme#1133) but we haven't fixed it yet. I just looked back at those issues and the related RTD enhancements (which are now deployed!) so it ought to be possible to get this resolved soon. The theme is overdue for a release so I'll try to sneak this one in before that happens.

[pllim]

Thank you, @drammock !

[pllim]

@drammock , do you think https://blog.readthedocs.com/addons-flyout-menu-beta/ would change how this is fixed over at pydata-sphinx-theme?

xref readthedocs/readthedocs.org#6297 (comment)

• Customization patterns readthedocs/addons#51
• User API: communicate with the library readthedocs/addons#13

[drammock]

I doubt it will change anything. We (PST) can't assume that RTD Addons is available/enabled by everyone (and anyway not all of our users' sites are hosted on RTD). The way the (still WIP!) fix is implemented in pydata/pydata-sphinx-theme#1133 should also not affect the new RTD-Addons-based flyout at all (since it's not injecting HTML at build time). I suppose if the RTD Addons approach became default before our fix ever got finalized, then it would render our fix moot 🤷🏻 but otherwise I think they're at least somewhat complementary.

[humitos]

Hi 👋🏼 . I'm one of the Read the Docs developers working on the new beta addons. I'm chiming in here since I'm in the design phase of customization & integration of the flyout and other addons into Sphinx (and other doctool) themes.

I've done a POC for this integration using the new beta addons and a JavaScript CustomEvent called readthedocs-addons-data-ready (not yet released) that contains a JSON structure with all the data required to nicely generate/render/integrate the flyout into the theme. See readthedocs/sphinx_rtd_theme#1526 for an example of how I'm using this data to render the flyout in the navbar at bottom left. I'd appreciate any feedback you may have about this.

Besides, we've deployed a way for project hosted on Read the Docs to opt-in into the new beta addons. To do this, project maintainers can

1. go to the beta dashboard (oh, yeah, we have a beta dashboard as well 😉), https://beta.readthedocs.org/
2. go to your project's settings (e.g. for astropy project, https://beta.readthedocs.org/dashboard/astropy/edit/)
3. then click on "Addons (Beta)" tab (e.g. for astropy project, https://beta.readthedocs.org/dashboard/astropy/addons/edit/)
4. click on "Enable" and "Save"

After that, if you open the Astropy's documentation on Read the Docs, it will have the new addons enabled and the flyout should appear floating at the bottom right showing the Read the Docs logo. I'd love you giving this a try and sharing any feedback you may have 🙏🏼

It's worth to note that the new beta addons have more features than the old integration. These new features currently are: "visual diff on pull requests" and "a improved search as-you-type UI/UX". Check https://github.com/readthedocs/addons#empower-your-docs-with-read-the-docs to see some examples.

[pllim]

Thanks, @humitos ! I followed your instructions and I think I see it now at bottom right on https://docs.astropy.org/en/latest/ as such:

When I click on a section, it goes to bottom left as before:

The I click on the logo to take me back to https://docs.astropy.org/en/latest/index.html as such:

But now the add-on that I saw on bottom right does not come back. Looks like it only shows up when index.html is not in the URL. Is this expected behavior?

[humitos]

Is this expected behavior?

No, it should appear in all the pages when enabled as it appears in the first screenshot you shared. I thought it could be related with the CDN cache, but I purged it and I'm experimenting the same as you after purging it as well.

I'm taking a look at it now and I'm not seeing anything too obvious at first sight. I will continue debugging this and come back with more info after that. Thanks a lot for giving this a try and sharing this feedback. It's super useful for us 🎉

[humitos]

I found the issue 💪🏼 . The problem was a "URL matching" issue. It seems that it worked for URL ending in trailing slash (e.g /en/latest/) but it didn't work for pages containing the filename at the end (e.g. /en/latest/index_user_docs.html)

I fixed the "URL matching" rule and it should behave as expected now. Please, confirm.

[pllim]

@humitos , I made a new build (https://beta.readthedocs.org/projects/astropy/builds/22007149/) after I received your message but I don't see any difference. Did I miss something here? I refreshed the pages on the browser.

[humitos]

I see the new flyout at the bottom right in all the pages now. Example: https://docs.astropy.org/en/latest/units/conversion.html

Also, I can confirm that the new beta addons are enabled in your project now, because if you go to a build from a pull request like https://astropy--15375.org.readthedocs.build/en/15375/ you will see the new notification:

Have you tried doing a "force refresh"? Maybe it's a caching issue?

Note that there is no need to perform a rebuild after enabling/disabling the new beta addons from the dashboard.

[pllim]

Have you tried doing a "force refresh"?

How do I do that? I have Chrome on Windows 10.

[humitos]

How do I do that? I have Chrome on Windows 10.

Ctrl + Shift + r should reload the page ignoring the local cache.

[pllim]

Ah, thanks! Indeed I see it now after force reload. As far as I am concerned, this is fixed for astropy. Thank you!!!

[pllim]

p.s. Does the beta dashboard have a dark mode? I cannot find any toggle for it. 😸

[humitos]

Ah, thanks! Indeed I see it now after force reload. As far as I am concerned, this is fixed for astropy. Thank you!!!

I'm happy to read it's working as you expected now 🚀

Does the beta dashboard have a dark mode?

No, it doesn't have dark mode for now 😅

[pllim]

Thanks for your help and quick replies! ❤️

No, it doesn't have dark mode for now

Where can I submit a feature request? 😆 (readthedocs/ext-theme#216)

[humitos]

You can submit the request at https://github.com/readthedocs/addons

[humitos]

Ah, I got confused. The said "the dashboard" but I read addons for some reason. I moved the issue to https://github.com/readthedocs/ext-theme which is the repository of the new dashboard