API: use `<meta>` to define supported API version and trigger `CustomEvent` #64

humitos · 2023-04-27T19:12:00Z

Let users to define <meta name="readthedocs-api-version" content="1.0"> to tell Read the Docs client what is the API scheme version supported by them.

When our client request the API data, if the api_version returned does not match with the one expected by the user, another request is done to force a particular API scheme version.

Then, we dispatch a readthedocsdataready custom event ~~and expose window.readthedocs~~, to let our users know this data is ready to be consumed by their own integrations.

Closes #60
Closes #61
Closes #17
Closes readthedocs/readthedocs.org#9957
Closes #250

src/readthedocs-config.js

public/index.html

src/readthedocs-config.js

Let users to define `<meta name="readthedocs-api-version" content="1.0">` to tell Read the Docs client what is the API scheme version supported by them. When our client request the API data, if the `api_version` returned does not match with the one expected by the user, another request is done to force a particular API scheme version. Then, we dispatch a `readthedocsdataready` custom event, to let our users know this data is ready to be consumed by their own integrations. Closes #60 Closes #61

humitos · 2023-04-27T21:41:40Z

@pradyunsg 👋🏼 -- I'm pinging you in this PR because this is the initial implementation for the pattern that we talked at PyCon to keep the integration stable as much as possible. I'd appreciate any feedback you may have here.

Let me know if connecting to the readthedocsdataready event as a theme author and having access to API response as JSON in event.detail would be enough for you.

Feel free to suggest any change you consider, from naming to full re-designing of the pattern 😉

pradyunsg · 2023-04-28T17:15:48Z

Haven't reviewed the logic/code but the description sounds great!

This new header will force the API endpoint to return a specific JSON version schema without taking into consideration the any other header. The idea behind this is to allow theme authors guarrantees about the JSON scheme they are expecting; without stopping us to move forward with potential changes required to the API response when adding new features/addons/etc. Related readthedocs/addons#64

… humitos/custom-event

Initial experimentation to use the `CustomEvent` triggered by the addons called `readthedocsdataready` event (from readthedocs/addons#64) to build the Read the Docs flyout being integrated into the theme keeping the original look & feel. * Related: readthedocs/addons#64 * Closes #1523

src/readthedocs-config.js

humitos · 2023-09-14T13:19:53Z

@pradyunsg I did a POC on the Read the Docs Sphinx theme using this idea of listening to a CustomEvent as a theme author to integrate the Read the Docs flyout addons in better/nicer/more styled way ✨ . See the PR at readthedocs/sphinx_rtd_theme#1526. This is not ready to be merged nor finished, but as I'm exploring with this and shaping out the final structure for this data and more, I'd love to have your feedback here 🙏🏼 . This will help us to know if we are building something that's going to be useful for theme authors and advanced users that want to have better integrations with Read the Docs.

… humitos/custom-event

src/readthedocs-config.js

* API: accept `X-RTD-Hosting-Integrations-API-Version` This new header will force the API endpoint to return a specific JSON version schema without taking into consideration the any other header. The idea behind this is to allow theme authors guarrantees about the JSON scheme they are expecting; without stopping us to move forward with potential changes required to the API response when adding new features/addons/etc. Related readthedocs/addons#64 * Remove old test * Use text for `api_version`, since it could be something like `0.1.2`

… humitos/custom-event

agjohnson

I noted how we could improve the promise flow here, the most important point is probably to be ensuring we stop the promise when we hit an error state though.

src/readthedocs-config.js

… humitos/custom-event

…tom-event

Integrate the new Read the Docs Addons JavaScript into the Python Docs Sphinx theme to render versions and languages selector nicely. References: * Discuss thread: https://discord.com/channels/935215565872693329/1159601953265942589 * Implementation of Addons JavaScript `CustomEvent`: readthedocs/addons#64

Integrate the new Read the Docs Addons JavaScript into the Python Docs Sphinx theme to render versions and languages selector nicely. References: * Discord thread: https://discord.com/channels/935215565872693329/1159601953265942589 * Implementation of Addons JavaScript `CustomEvent`: readthedocs/addons#64 * Conversation about using Read the Docs: python/docs-community#5

humitos · 2024-03-19T10:15:26Z

I updated this PR with the latest changes on main and made some minor adjustments. @agjohnson can you please review it?

I opened a POC on the CPython repository that requires the work from this PR to render the language and version selector on their documentation: python/cpython#116966

I've been talking to them via Discord and they are thinking about merging that PR soon to continue with the experimentation about hosting their docs on Read the Docs.

agjohnson

This looks good to me. Overall, I would still point you towards using Promise instances more often, as this pattern does help tame promise chaining and nesting rather well.

Follow Anthony's suggestion from #64 (comment)

agjohnson

The promise logic change looks good 👍

Edit: oookay, I was confused why the logic didn't seem different here. I saw the commit eb550b above and thought it was in this PR 😅

I just realized this from a commit in #286 instead. I think we can merge this and tune the logic afterwards.

Implements the changes in the API made in readthedocs/readthedocs.org#11205. We need to merge that PR and deploy addons together with the changes in this PR. In this PR there are mainly no changes in the logic. The most important thing to mention here is that we are standardizing the usage of the API response and pinning to `v1` now (we were using `v0-alpha`). This means: - we will be exposing the `v1` to users via the js custom event (see #64) - we are using standard/shared APIv3 serializers for resources for this `/addons/` endpoint - any breaking change we have to do in the future it will increase the API response version I'm not sure there are too much to review here, but I'd appreciate at least a quick look at these changes. I'm happy to answer some questions you may have here or on the underlying PR about the API response changes. ### Related: * Closes #132 * Unblocks #265 * Unblocks theme integration (our theme and CPython's one) * Requires readthedocs/readthedocs.org#11205 --------- Co-authored-by: Anthony <aj@ohess.org>

Follow Anthony's suggestion from #64 (comment)

…tom-event

…into humitos/custom-event

humitos · 2024-04-15T09:28:28Z

🎉

humitos requested a review from a team as a code owner April 27, 2023 19:12

humitos requested a review from agjohnson April 27, 2023 19:12

humitos force-pushed the humitos/custom-event branch from 00120b5 to f3eaa7a Compare April 27, 2023 19:17

humitos commented Apr 27, 2023

View reviewed changes

src/readthedocs-config.js Outdated Show resolved Hide resolved

agjohnson reviewed Apr 27, 2023

View reviewed changes

src/readthedocs-config.js Outdated Show resolved Hide resolved

agjohnson reviewed Apr 27, 2023

View reviewed changes

public/index.html Outdated Show resolved Hide resolved

src/readthedocs-config.js Outdated Show resolved Hide resolved

humitos force-pushed the humitos/custom-event branch from f3eaa7a to 2fdb6c8 Compare April 27, 2023 21:37

humitos mentioned this pull request Apr 28, 2023

API: return the api_version on the response readthedocs/readthedocs.org#10276

Merged

humitos mentioned this pull request Apr 28, 2023

Document theme developer development/mocking patterns #59

Open

This was referenced Sep 6, 2023

Flyout: more visible language selection readthedocs/readthedocs.org#9957

Closed

Flyout: better language switcher #250

Closed

Merge branch 'main' of github.com:readthedocs/readthedocs-client into…

0590838

… humitos/custom-event

humitos mentioned this pull request Sep 13, 2023

Addons: integrate with new beta addons flyout readthedocs/sphinx_rtd_theme#1526

Open

humitos added 2 commits September 13, 2023 18:00

Allow CORS on development server

26bab87

Serve the .js file from where the server is running

c3b0edb

humitos commented Sep 13, 2023

View reviewed changes

src/readthedocs-config.js Outdated Show resolved Hide resolved

humitos added 2 commits September 19, 2023 12:01

Merge branch 'main' of github.com:readthedocs/readthedocs-client into…

a31c257

… humitos/custom-event

Update the code with the latest changes and ideas

f8de57b

humitos changed the title ~~API: use <meta> to define supported API version~~ API: use <meta> to define supported API version and trigger CustomEvent Sep 19, 2023

humitos mentioned this pull request Sep 19, 2023

Customization patterns #51

Open

humitos commented Sep 20, 2023

View reviewed changes

src/readthedocs-config.js Outdated Show resolved Hide resolved

humitos added 2 commits September 21, 2023 12:35

Merge branch 'main' of github.com:readthedocs/readthedocs-client into…

cb12f5d

… humitos/custom-event

Typo

c28fe6d

humitos requested a review from agjohnson October 10, 2023 15:31

agjohnson reviewed Oct 16, 2023

View reviewed changes

src/readthedocs-config.js Outdated Show resolved Hide resolved

src/readthedocs-config.js Outdated Show resolved Hide resolved

src/readthedocs-config.js Outdated Show resolved Hide resolved

Merge branch 'main' of github.com:readthedocs/readthedocs-client into…

2a6ed87

… humitos/custom-event

humitos mentioned this pull request Jan 15, 2024

Defer loading of badge_only.css? readthedocs/readthedocs.org#9134

Closed

humitos mentioned this pull request Feb 21, 2024

add API to get available/current version from JavaScript readthedocs/readthedocs.org#9875

Open

humitos mentioned this pull request Mar 13, 2024

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

Closed

humitos added 3 commits March 18, 2024 16:47

rebuild assets

63f6421

Merge branch 'main' of github.com:readthedocs/addons into humitos/cus…

7784008

…tom-event

merge conflict

d947647

humitos mentioned this pull request Mar 18, 2024

Doc: Render version/language selector on Read the Docs python/cpython#116966

Merged

humitos added 3 commits March 19, 2024 11:01

Minor updates after merging

e18bd1c

Throw an exception and handle it properly

e8ec758

Simplify dispatching the event

7a5c1e4

humitos requested a review from agjohnson March 19, 2024 10:13

Catch the error properly

fcfa1e6

agjohnson approved these changes Mar 21, 2024

View reviewed changes

humitos mentioned this pull request Apr 8, 2024

API: simplify and standardize data usage #281

Merged

humitos added a commit that referenced this pull request Apr 9, 2024

Refactor getReadTheDocsConfig to use Promise

eb5506b

Follow Anthony's suggestion from #64 (comment)

humitos mentioned this pull request Apr 9, 2024

Refactor getReadTheDocsConfig to use Promise #286

Merged

agjohnson approved these changes Apr 9, 2024

View reviewed changes

humitos added 3 commits April 15, 2024 10:58

Refactor getReadTheDocsConfig to use Promise (#286)

98768a4

Follow Anthony's suggestion from #64 (comment)

Merge branch 'main' of github.com:readthedocs/addons into humitos/cus…

9af151c

…tom-event

Merge branch 'humitos/custom-event' of github.com:readthedocs/addons …

6019cc0

…into humitos/custom-event

humitos merged commit 0b06297 into main Apr 15, 2024
4 checks passed

humitos deleted the humitos/custom-event branch April 15, 2024 09:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API: use `<meta>` to define supported API version and trigger `CustomEvent` #64

API: use `<meta>` to define supported API version and trigger `CustomEvent` #64

humitos commented Apr 27, 2023 •

edited

humitos commented Apr 27, 2023

pradyunsg commented Apr 28, 2023

humitos commented Sep 14, 2023

agjohnson left a comment

humitos commented Mar 19, 2024

agjohnson left a comment

agjohnson left a comment •

edited

humitos commented Apr 15, 2024

API: use <meta> to define supported API version and trigger CustomEvent #64

API: use <meta> to define supported API version and trigger CustomEvent #64

Conversation

humitos commented Apr 27, 2023 • edited

humitos commented Apr 27, 2023

pradyunsg commented Apr 28, 2023

humitos commented Sep 14, 2023

agjohnson left a comment

Choose a reason for hiding this comment

humitos commented Mar 19, 2024

agjohnson left a comment

Choose a reason for hiding this comment

agjohnson left a comment • edited

Choose a reason for hiding this comment

humitos commented Apr 15, 2024

API: use `<meta>` to define supported API version and trigger `CustomEvent` #64

API: use `<meta>` to define supported API version and trigger `CustomEvent` #64

humitos commented Apr 27, 2023 •

edited

agjohnson left a comment •

edited