Addons flyout and old versions

[tsibley]

Continuing a conversation started by @victorlin here, at the request of @humitos.

We have many old versions of doc projects with the older build-time RTD injections (e.g. readthedocs-doc-embed.js). These are forcibly removed and replaced by the newer on-the-fly RTD Addons injections. While the previous injections let old versions show an up-to-date flyout attached to the sidebar, the new injections only support a floating flyout in the bottom right. We can remove the floating flyout by disabling the Addons flyout, but the removal of the older injections still happens and so the result is no flyout at all for older versions. As the only way to customize the new Addons flyout is via the theme, that leaves us no way but rebuilding dozens of old doc versions if we want to maintain the previous functionality of a sidebar-attached flyout.

Would you consider making the removal of the relevant old injections conditional on if the Addons flyout is actually enabled? Or conditional on build time being after the date addons were enabled for a project?

[humitos]

Hi @tsibley! Currently, we don't support too much customization on the addons flyout, but we are exploring different ideas to allow users to customize it in different ways -- as you found in the issue you linked.

Note that we removed the old injected flyout because it's deprecated and will be removed in the near future. It depends on different things we are not able to maintain anymore and that was one of the reason why we re-created it as an addon. So, even if we allow the old behavior in old versions it will stop working soon.

I recommend you to use the addons floating flyout in your projects for now since it fulfill your needs of showing a version selector in all the versions, old and new ones. I understand it's not a perfect solution due to its style, but it solves the problem at least.

In the future, when we add support for extra customization, you will your projects already prepared for this.

That's the solution I can offer to you for now. However, I will talk to other Read the Docs folks and see if they have different ideas here.

[tsibley]

Note that we removed the old injected flyout because it's deprecated and will be removed in the near future. It depends on different things we are not able to maintain anymore and that was one of the reason why we re-created it as an addon. So, even if we allow the old behavior in old versions it will stop working soon.

I'm confused about "removed in the near future". It's being actively removed right now.

It would be easier to not remove it by not rewriting the outgoing HTML. But I guess you're saying that RTD does not want to (or can't?) maintain the endpoint(s) the old flyout needs? It's not clear why when the new flyout has the same information.

[ericholscher]

@tsibley We talked about this today, and definitely want to find a way forward to make things work well for you. We're working to build more customization in the long term, but also have a couple options in the short term.

We're able to inject a custom bit of JS into all of your versions that you can use to recreate some of the flyout, similar to the RTD theme, and then hide the new flyout for now until we can work to build a better integration for you. Does that make sense as a shortterm workaround?

Our vision for the future is for theme authors to use this data and the custom event to integrate the data directly into the theme, perhaps not having a flyout at all. We're viewing the flyout as a default implementation, but with access to the raw data, hopefully versions, translations, downloads, and search can be built into the docs explicitly (for example: https://docs.readthedocs.io/en/stable/intro/sphinx.html#configure-read-the-docs-search)

Please let me know what would make things better in the short term and we want to work with you on making the migration easier, and ensuring we end up in a better place.

[victorlin]

Hi @ericholscher, I'll respond since @tsibley is out until next week.

We would be happy to consider the short term workaround. I'm curious what "recreate some of the flyout" means. Could we first apply this on a test project? That would be https://docs.nextstrain.org/projects/sphinx-theme/ where I've already disabled the new flyout addon.

Thank you for your efforts 🙏

[ericholscher]

We would be happy to consider the short term workaround. I'm curious what "recreate some of the flyout" means. Could we first apply this on a test project? That would be https://docs.nextstrain.org/projects/sphinx-theme/ where I've already disabled the new flyout addon.

Yea, we can definitely do a test project. Mostly was referring to recreating the old HTML structure, like what the RTD theme is doing -- so that you can get the old functionality, but with the new Addons & custom event approach.

Thank you for your efforts 🙏

Appreciate the kind words. It's been a stressful week, and we're trying to get things to a better place moving forward!

[tsibley]

We're able to inject a custom bit of JS into all of your versions that you can use to recreate some of the flyout, similar to the RTD theme, and then hide the new flyout for now until we can work to build a better integration for you. Does that make sense as a shortterm workaround?

Thanks for this offer. If this is a short-term (temporary?) solution, what's the long-term solution for old versions?

How should we ship the JS to you for the custom injection?

[ericholscher]

We're able to inject a custom bit of JS into all of your versions that you can use to recreate some of the flyout, similar to the RTD theme, and then hide the new flyout for now until we can work to build a better integration for you. Does that make sense as a shortterm workaround?

Thanks for this offer. If this is a short-term (temporary?) solution, what's the long-term solution for old versions?

I think that solution should work long-term, but it's a fix for only a subset of projects. We're hoping to have a larger systemic solution, but still trying to figure out the best path there.

How should we ship the JS to you for the custom injection?

You can post it here, or send it via email to us at [email protected].