Deprecation: Removal of Sphinx context injection at build time

[victorlin]

Brief summary from email:

We are announcing the deprecation of Sphinx context injection at build time for all the projects. The deprecation date is set on Monday, October 7th, 2024. After this date, Read the Docs won't install the readthedocs-sphinx-ext extension and won't manipulate the project's conf.py file.

Tasks

• Read through the blog post on the deprecation
• Skim sphinx-rtd-theme version 3.0.0 changelog and configuration doc page for 3.0.0-related changes

In our base theme (nextstrain-sphinx-theme) or across individual docs projects:

• Manually inject READTHEDOCS to html_context (GitHub search)
  • in nextstrain-sphinx-theme
• Figure out what to do about the flyout changes (ref)
  • in nextstrain-sphinx-theme
• Replace display_version with version_selector (GitHub search)
  • Changes for sphinx-rtd-theme 3.0.0 #230

[tsibley]

I read thru the "Read the Docs Addons enabled by default" blog post just now. Some notes:

1. We use the READTHEDOCS template var, so will need to make the build-time config changes noted in the blog post.
2. We'll want to set sphinx-rtd-theme's new (as of 2.1.0rc2) config option flyout_display = "attached" in our Sphinx theme and hide the floating flyout produced by the new addon.
3. We may need to adapt parts of our sphinx-theme to account for changes to the newer sphinx-rtd-theme version

[tsibley]

The changes upstream have caused our docs to start rendering with a floating flyout instead of a fixed docs info/version switcher.

[victorlin]

I updated the task list with everything that @tsibley has uncovered so far. The list seems to be comprehensive, based on my reading of the blog post and sphinx-rtd-theme 3.0.0 changes.

[victorlin]

I considered keeping the new floating flyout – on wide screens, it makes use of the extra space on the right side of the docs and allows for more sidebar content to be shown. But on narrower screens, it covers our actual docs. Covering sidebar content is probably a better trade-off across screen sizes?

[tsibley]

The floating flyout drives me batty, as it's continually in the way. Would definitely prefer to keep it in the sidebar.

[victorlin]

Restoring the sidebar flyout is not as simple as setting flyout_display = "attached" and hiding the RTD addon flyout. I've posted readthedocs/readthedocs.org#11474 (comment) hoping to find a path forward.

Here's an example showing why it doesn't work with nextstrain/sphinx-theme@572d534 + disabling the flyout addon (I'll fix this after we settle on a solution for other projects): Go to the PR build and use the flyout to switch to an older version. The older version no longer has a flyout.

[victorlin]

Given that the new flyout addon is floating-only and can only be disabled per project (not per version), these are our options:

1. Use the floating flyout everywhere. This is the status quo as of the forced upgrade last week.
2. Use the sidebar flyout on new versions and no flyout on old versions. Adding this just to be exhaustive – having no flyout on old versions seems like a non-starter.
3. Use the sidebar flyout everywhere by rebuilding all older versions with flyout_display = "attached". Rebuilds could come with other problems if not done properly.

Seems like we may have to stick with the floating flyout.

[tsibley]

@victorlin Gah. Rebuilding old versions, while doable in theory, is likely in practice to cause other issues.

The per-project limitation is really hamstringing us here. There's discussion of that limitation and related ones (e.g. no reproducible builds) being an issue in readthedocs/addons#51, but nothing brought up there was addressed before this big addons change got pushed thru.

[tsibley]

readthedocs/readthedocs.org#11677

[victorlin]

Thank you for following up 🙏

[tsibley]

There's one stupid thing we could do…

[tsibley]

Another issue with the new addons is the search switcheroo which now doesn't search subprojects by default (unlike the old search):

The search results now also lack search term highlighting, and I, at least, find the search modal results much less useful and information-dense than the previous results page. Sigh.

Adding to this, the old cross-project search is intentionally disabled, so disabling the new search addon doesn't even restore the previous functionality: it reverts to more limited search functionality we never used (Sphinx's built in). Double sigh.

[tsibley]

There's one stupid thing we could do…

Looks like this is the direction we may be headed after all…? Oy vey.