Addons: integrate with new beta addons flyout

[humitos]

Initial experimentation to use the CustomEvent triggered by the addons called readthedocs-addons-data-ready event (from readthedocs/addons#64) to build the Read the Docs flyout being integrated into the theme keeping the original look & feel.

How to test it

1. Build 'n Serve the documentation setting READTHEDOCS variable

READTHEDOCS=True sphinx-autobuild --watch sphinx_rtd_theme/versions.html -a --port 9999 --host 0.0.0.0 docs docs/_build/html

2. Start the addons development server from humitos/custom-event branch

cd readthedocs/addons
git checkout origin/main
npm run dev

3. Open the browser at http://localhost:9999/ (note that we are using localhost here)

Example

Note

I added these lines in versions.html

<meta name="readthedocs-resolver-filename" content="/" />
<script type="text/javascript" src="http://localhost:8000/readthedocs-addons.js"></script>

and also hardcoded the URL to hit in the readthedocs-config.js addons file as

  url = "http://docs.devthedocs.org/_/addons/?project-slug=docs&version-slug=latest&client-version=0.12.0&api-version=1";

and used Firefox CORS Addon to allow CORS with the development instance

---

• Requires: API: use <meta> to define supported API version and trigger CustomEvent addons#64
• Closes Integrate the new addons flyout into the theme #1523

[agjohnson]

Noted on a call today, we should start trying out these changes for some of our own projects to start. This would serve as a working example for other authors, and gives us something to test against.

[humitos]

Not sure how complete this is, I didn't test this locally. But this seems on the right path

It's great knowing that we are going in the right direction. The PR is not finished or ready to merge yet, but I wanted to have a review at this stage to know if we are aligned here and it seems we are 👍🏼

[humitos]

With the latest changes, it looks great to me! I think we are ready to merge readthedocs/readthedocs.org#11279 so we can start testing it out in our documentation.

[agjohnson]

Yeah lets merge the docs PR 👍 This seems close enough to start testing

[agjohnson]

We discussed next steps here today, and I think to consider an alpha/beta release of this, we should use the existing patterns for JS/CSS instead. Besides that, this all seems fairly close.

We talked about testing this with more internal projects, which is a good step as well. I don't see to much changing besides finishing the JS/CSS.

[humitos]

I made the requested changes 👍🏼 . It seems everything keeps working fine: https://docs.readthedocs.io/en/latest/

[humitos]

Failing tests are unrelated with the changes on this PR. It seems the latest Sphinx/docutils version changed something in the HTML structure and we will need to update our test case.

[humitos]

@agjohnson can you take a look at this PR? I'd like to move forward with an alpha release, so we can start testing it with some particular users.

[agjohnson]

I haven't had time to do too deep a review here, but this looks like it should be close enough. 👍

We'll likely need to use the beta period to debug issues with this a bit, as it can be hard to code defensively in string interpolations.

[humitos]

Cool! I'm merging this PR now. We can coordinate the release of an alpha/beta version after that 👍🏼