Flyout: can't be injected into custom HTML element

[mowies]

Since the beta was enable for the keptn project, the flyout menu is not injected into our designated place anymore.
I looked at the addon code for the new flyout menu already and didn't find anything about injection into custom places.
It would be great to have that feature!

[humitos]

Hi @mowies. Currently, the flyout only has that position. However, we have been working on a way to let users customize the whole rendering of it by subscribing to a JavaScript CustomEvent that contains all the data in JSON that Read the Docs exposes.

• Implementation of the CustomEvent: API: use <meta> to define supported API version and trigger CustomEvent #64
• Integration into the Sphinx Read the Docs theme: Addons: integrate with new beta addons flyout sphinx_rtd_theme#1526

Note we don't plan to perform this integration on each of the theme, but expose the data and JS event so users can subscribe to it and render the flyout as they want.

I would appreciate any feedback you may provide on this approach, since it's still under development.

[mowies]

Cool that it's being worked on!
Although I think the injection solution is much more elegant since no additional custom JS is needed to actually render it.
On the other hand, that means that theme developers don't need to follow whatever the flyout menu HTML uses in terms of classes etc. for styling.

[humitos]

@mowies the PR #64 was already merged and deployed. You should be able to subscribe to readthedocs-addons-data-ready event and use event.detail.data() to get the Read the Docs data exposed and generate version/language selectors where you wish. Unfortunately, we don't have documentation written about this yet, but here you have 2 examples for this integration:

• Example Material for MkDocs project: https://github.com/readthedocs/test-builds/blob/59af3cbe757eea354f7dd1320747f691d928dce2/docs/javascripts/readthedocs.js#L10-L33
• Example on CPython documentation (Sphinx): Doc: Render version/language selector on Read the Docs python/cpython#116966

Let me know if this is helpful for you and/or if you have any doubt about how to integrate this selectors into your project.

[humitos]

By the way, the Material for MkDocs integration can be seen live at https://test-builds.readthedocs.io/en/mkdocs-material/ and the CPython's one can be seen live at https://cpython-previews.readthedocs.io/en/main/.

I will close this issue since there is any action from our side, but I'm happy to receive any feedback you may have here. Also, feel free to open another issue if you have any doubt or something is not working as expected.