Version 3.0.0rc1 no longer includes version selector

[alex]

Problem

When testing with 3.0.0rc1, the version selector is no longer present.

Reproducible Project

pyca/cryptography#11460 (https://cryptography--11460.org.readthedocs.build/en/11460/)

Expected Results

There is a version selector.

Environment Info

• Python Version: 3.11.9
• Sphinx Version: 8.0.2
• RTD Theme Version: 3.0.0rc1

[humitos]

Thanks for reporting this issue. This is the expected behavior and that's why the change was included in a major version. I could have been more explicit about this particular change in my comments to avoid confusions, tho 😄

This change is strictly related with "Read the Docs Addons being enabled by default on October 7th" as we announced a few weeks ago.

To keep rendering the flyout, you first have to enable Read the Docs Addons on your project by following these steps.

Once you have addons enabled, there are two different options to render the flyout:

1. Use the Read the Docs Addons' flyout (recommended)
   • On the settings page where you enabled addons, keep Flyout enabled checked.
   • This will add the default floating flyout at the bottom right immediately without re-building your docs.
2. Use the Sphinx Theme's flyout ¹
   • On the settings page where you enabled addons, uncheck Flyout enabled.
   • In your conf.py define the flyout_display as "attached".
   • Re-build your documentation to see the flyout in the bottom left into the navbar.

I'd really appreciate your feedback about this. We are in the middle of a transition and I'm aware that all of this could be consfusing, but we are trying our best to clarify things as much as possible before reaching the date when addons will be enabled by default. I hope all of this makes sense. Let me know.

Footnotes

1. we expect this behavior to change in the future -- Ideally, we would split the flyout content into different components (eg. version and language selectors) and integrate them better into the theme itself, instead of being a box with a bunch of content. Similar to what CPyhton docs does. See the top-left selectors at https://docs.python.org/3/ as example. ↩

[alex]

I think it'd be helpful to have this context somewhere in the sphinx-rtd-theme changelog or similar. I looked at the diff between the releases and added the flyout_display = "attached" but didn't realize there was more to do.

Thanks for your detailed answer.

[alex]

I should also note: with this resolved, 3.0.0rc1 seems great and I'm looking forward to a release.

[alex]

Is there anything required for the rc1 to become a final release?

[ssbarnea]

@humitos Can we please have the 3.0 release out? There are important issues already fixed in it (like docutils update).

[humitos]

Hi! We are waiting until October 7th to release the 3.0.0 final since it adds a breaking change that requires Read the Docs Addons enabled by default. In the meanwhile, we will use September as a period to receive feedback and fix any issue we may find.

[eMUQI]

Thanks for reporting this issue. This is the expected behavior and that's why the change was included in a major version. I could have been more explicit about this particular change in my comments to avoid confusions, tho 😄

This change is strictly related with "Read the Docs Addons being enabled by default on October 7th" as we announced a few weeks ago.

To keep rendering the flyout, you first have to enable Read the Docs Addons on your project by following these steps.

Once you have addons enabled, there are two different options to render the flyout:

1. Use the Read the Docs Addons' flyout (recommended)

   • On the settings page where you enabled addons, keep Flyout enabled checked.
   • This will add the default floating flyout at the bottom right immediately without re-building your docs.

2. Use the Sphinx Theme's flyout 1

   • On the settings page where you enabled addons, uncheck Flyout enabled.
   • In your conf.py define the flyout_display as "attached".
   • Re-build your documentation to see the flyout in the bottom left into the navbar.

I'd really appreciate your feedback about this. We are in the middle of a transition and I'm aware that all of this could be consfusing, but we are trying our best to clarify things as much as possible before reaching the date when addons will be enabled by default. I hope all of this makes sense. Let me know.

Footnotes

1. we expect this behavior to change in the future -- Ideally, we would split the flyout content into different components (eg. version and language selectors) and integrate them better into the theme itself, instead of being a box with a bunch of content. Similar to what CPyhton docs does. See the top-left selectors at https://docs.python.org/3/ as example. ↩

@humitos Hello, I used the second method to use Sphinx Theme's flyout. However, the version selector has become unclickable. I'm not sure if this is an issue with sphinx_rtd_theme, Sphinx, or my settings. Could you please take a look?

docs/requirements.txt: sunfounder/universal-maker-sensor-kit@c235fa2

docs/source/conf.py: sunfounder/universal-maker-sensor-kit@23c787e

Here is my documentation link: https://docs.sunfounder.com/projects/umsk/en/latest/

[humitos]

@eMUQI it seems that you are not installing the theme as a Sphinx extension which is required to load jQuery. Take a look at https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html

[eMUQI]

@eMUQI it seems that you are not installing the theme as a Sphinx extension which is required to load jQuery. Take a look at https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html

@humitos Thanks, it works now!

[humitos]

We released 3.0.0rc2 that includes #1601 and it looks like this:

We will keep working on this approach in the future since we consider it as a better way to integrate the version/language selectors than re-implementing the flyout completely.

You can see a live example at https://sphinx-rtd-theme.readthedocs.io/en/latest/

---

Another example with multiple versions and translations: https://test-builds.readthedocs.io/en/latest/