Flyout: can't be injected into custom HTML element #276

Activity

1. humitos commented on Mar 13, 2024

   

   humitos

   on Mar 13, 2024

   Member

   More actions

   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.
2. humitos

   changed the title [-]Flyout menu can't be injected into custom HTML element[/-] [+]Flyout: can't be injected into custom HTML element[/+] on Mar 13, 2024
3. humitos

   added this to 📍Roadmapon Mar 13, 2024
4. github-project-automation

   moved this to Planned in 📍Roadmapon Mar 13, 2024
5. humitos

   added

   FeatureNew featureNew feature

   on Mar 13, 2024
6. mowies commented on Mar 13, 2024

   

   mowies

   on Mar 13, 2024

   Author

   More actions

   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.
7. humitos

   self-assigned this

   on Apr 9, 2024
8. humitos commented on Apr 22, 2024

   

   humitos

   on Apr 22, 2024

   Member

   More actions

   @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.
9. humitos commented on Apr 25, 2024

   

   humitos

   on Apr 25, 2024

   Member

   More actions

   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.
10. humitos

    closed this as completedon Apr 25, 2024
11. github-project-automation

    moved this from Planned to Done in 📍Roadmapon Apr 25, 2024