Flyout and Footer API design document #8052

davidfischer · 2021-03-25T20:19:49Z

This is a design document for using APIv3 in order to generate the flyout (version selector) menu. This is purely a proposal at this point to get everyone on the same page with respect to goals and how it could be implemented.

The main goals are to:

Give themes and projects a way to control the flyout menu. More than just CSS styling, they could take the raw data and put it into the navigation or other menus. For example, this would allow building Django's version selector menu instead of using RTD's default. A custom Sphinx or MkDocs theme could take on this work or a project could override it themselves.
Use the new APIv3 endpoint instead of an undocumented APIv2 endpoint that we're trying to deprecate.
Provide a baseline for overriding various other aspects of how Read the Docs customizes documentation.

For easier reading, there's a link to the document.

Closes #7748

stsewd · 2021-03-26T00:15:04Z

docs/development/design/flyout-redesign.rst

+.. code-block:: javascript
+
+    window.readthedocs = window.readthedocs || {};
+    window.readthedocs.customizations = {disable_custom_search: true, disable_version_selector: true};


we already do this, but we haven't document them. I like more the name you are proposing here p:

READTHEDOCS_DATA.features.docsearch_disabled

I know we do this. I like the idea a lot but I wish it was easier for users to control as well as documented. The way it is now can run into race conditions with us defining these features and users setting them.

stsewd · 2021-03-26T00:16:05Z

docs/development/design/flyout-redesign.rst

+.. code-block:: javascript
+
+    window.readthedocs = window.readthedocs || {};
+    window.readthedocs.integration_version_selector = function () {};


I'd name this custom_version_selector maybe? Wasn't obvious for me that this was a custom function to inject the footer.

I'd also call it something other than version_selector since it does a lot more than that.

stsewd · 2021-03-26T00:24:09Z

docs/development/design/flyout-redesign.rst

+
+
+Overlap with existing API endpoints
+-----------------------------------


Just a note here that we are using the proxied endpoint of the footer, this /_/api/v2/footer_html, this allow us to share the same domain with some advantages:

avoid being blocked by some extensions

Allow to cache the response (docs are served from cloudflare)

Allow to use the auth backends in .com

And, I've been having some ideas around our APIs... here is an extract from #8039

We should probably make a distinction between our general API that handles Read the Docs resources,
vs our APIs that expose features (like server side search, footer, and embed, all of them proxied).
This way we can version each endpoint separately.

I do agree that the footer shares a lot with the projects/ endpoint. Proxying api v3 may be a little of a problem, because it relies heavily on resolving URLs from the dashboard, but in proxito we don't have the url patterns from the main site.

This is a very good point. Maybe we don't need all the APIv3 endpoints but we can have an endpoint that just returns the same data as the APIv3 endpoint and shares code.

humitos

The proposal looks good to me. I don't have too many comments on the JS implementation side, but seems it will work to me.

I'm not convinced that it's a good idea to share the APIv3 endpoint for the flyout to a regular endpoint. I think having independence and granular control here is better.

docs/development/design/flyout-redesign.rst

humitos · 2021-03-29T09:55:17Z

docs/development/design/flyout-redesign.rst

+Currently, there are separate API endpoints for translations and downloads,
+but ideally all the data needed to generate a version selector would be available from a single API.


It seems that we could implement ?expand=translations,subrpojects and we would have everything we need with one API call: https://readthedocs.org/api/v3/projects/docs/?expand=active_versions,translations,subprojects

One downside that has using this endpoint is that we will be returning much data than we need and that could slow down the response time.

Another thing to consider is that APIv3 is authenticated-only, and we require anonymous access for the flyout.

I'm not sold on the idea of sharing the endpoint for the flyout than a regular endpoint. In the future we may want to add extra data to /api/v3/projects/ and we may be blocked because it increases the response time by some milliseconds that are not acceptable for the flyout endpoint.

I think that having an independent endpoint with more control over it is a win here and will avoid headaches in the future.

Agreed here. I think we want a dedicated API just for this use, but it could share code for sure. The footer API is large enough of a use-case to make it special.

Also agree here, one flyout API seems like the best method. We don't yet have a good pattern for injecting an API access token into the build process, and this would be needed for all of the authenticated API endpoints.

Co-authored-by: Manuel Kaufmann <[email protected]>

ericholscher

This is a good start. I think we probably need to clarify our names a good bit here, but I like the general approach here. I don't know enough about JS to really judge alternative implementations though. I know our ad client works in a much more complicated way, but I'm not sure if that's because it's used on more sites, or why that design was chosen.

In particular, I think we need to clarify and standardize on names for:

What this API is called. footer isn't really correct. I think probably it's flyout_data or something like that? dynamicproject_data`?
What the flyout is called? I think we generally standardized on flyout but this doc uses version_selector. Should we remove flyout for the various composite parts?

I'm sure there's more named needed, but those were the two obvious ones. Names are hard.

ericholscher · 2021-03-30T22:57:24Z

docs/development/design/flyout-redesign.rst

+.. code-block:: javascript
+
+    window.readthedocs = window.readthedocs || {};
+    window.readthedocs.integration_version_selector = function () {};


I'd also call it something other than version_selector since it does a lot more than that.

ericholscher · 2021-03-30T22:59:20Z

docs/development/design/flyout-redesign.rst

+Currently, there are separate API endpoints for translations and downloads,
+but ideally all the data needed to generate a version selector would be available from a single API.


Agreed here. I think we want a dedicated API just for this use, but it could share code for sure. The footer API is large enough of a use-case to make it special.

agjohnson

I'm still considering the effects of using global state to configure the client. Generally, having a fully instantiated object is a more expected pattern and an easier pattern to work with if the user wants to extend functionality instead of replace it.

agjohnson · 2021-04-01T17:20:29Z

docs/development/design/flyout-redesign.rst

+
+    // This first line helps handle the case where the project/theme's overrides
+    // are executed before the readthedocs global is defined.
+    window.readthedocs = window.readthedocs || {};


One seemingly common use case that is not supported by this current proposal is extending the flyout display function/method. If a theme wants the flyout, but also wants to inject a version selector somewhere else in the UI, there is no way to extend this functionality, only override it.

That is, the user is expected to define a window.readthedocs.integration_version_selector to customize the display process, but there is no way to call the parent window.readthedocs.integration_version_selector function -- it isn't defined until after it is inspected by our client.

This could either be a reason to use a different pattern than defining overrides as global state, or we would need to require more granular override points for users.

agjohnson · 2021-04-01T17:24:29Z

docs/development/design/flyout-redesign.rst

+Currently, there are separate API endpoints for translations and downloads,
+but ideally all the data needed to generate a version selector would be available from a single API.


Also agree here, one flyout API seems like the best method. We don't yet have a good pattern for injecting an API access token into the build process, and this would be needed for all of the authenticated API endpoints.

agjohnson · 2021-04-01T18:19:50Z

docs/development/design/flyout-redesign.rst

+* This proposal doesn't involve creating an integration point to control custom search.
+  That could happen at a later date.
+* This proposal doesn't rework how the version selector looks either on the RTD Sphinx theme
+  or on other themes by default. Any restyling can be done independently of this.


Also, for this proposal to work for commercial users that are currently manipulating the flyout via CSS rules, we have to output the exact same DOM structure that we would normally return with the HTML blob. This is a little unfortunate, as the DOM structure could already stand to be designed better. We can adapt this later, but this might also hint at some support for multiple versions of DOM output.

stale · 2021-06-02T18:00:09Z

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

humitos · 2023-06-13T11:45:26Z

Things have changed considerably here with the introduction of the addons in https://github.com/readthedocs/readthedocs-client. I think it's safe to close this PR or, if we want, merge and close so we don't loose the document. Maybe adding a note in the top of it linking to the addons repository?

agjohnson · 2023-06-13T16:16:44Z

Maybe we just keep this available for reference on this branch? Merging this could be confusing for anyone that comes across this first, as we deviated from this plan a bit. I agree adding a note would help either way though 👍

humitos · 2023-06-21T13:50:43Z

I updated the warning note and I will merge it after that.

humitos

I'm approving this PR so it gets merged automatically after the check pass. Note that this work is not implemented and most of it was replaced by https://github.com/readthedocs/readthedocs-client and its new endpoint (/_/readthedocs-config/)

Flyout and Footer API design document

90bba8e

davidfischer requested a review from a team March 25, 2021 20:19

stsewd reviewed Mar 26, 2021

View reviewed changes

ericholscher mentioned this pull request Mar 26, 2021

Components for ReadTheDocs stuff pradyunsg/sphinx-basic-ng#12

Open

humitos reviewed Mar 29, 2021

View reviewed changes

Update docs/development/design/flyout-redesign.rst

28432a4

Co-authored-by: Manuel Kaufmann <[email protected]>

humitos mentioned this pull request Mar 30, 2021

Make flyout menu scrollable #7375

Closed

ericholscher reviewed Mar 30, 2021

View reviewed changes

agjohnson reviewed Apr 1, 2021

View reviewed changes

pradyunsg mentioned this pull request Apr 11, 2021

Make the top of page more easily reachable pradyunsg/furo#39

Closed

This was referenced May 10, 2021

Migration of theme to modern responsive theme python/docs-community#1

Open

Enhancing the switchers setup python/docs-community#4

Open

stale bot added the Status: stale Issue will be considered inactive soon label Jun 2, 2021

ericholscher added the Accepted Accepted issue on our roadmap label Jun 2, 2021

stale bot removed the Status: stale Issue will be considered inactive soon label Jun 2, 2021

abravalheri mentioned this pull request Jun 5, 2021

Experiment: Change in the Sphinx Theme pyscaffold/pyscaffold#453

Merged

ericholscher mentioned this pull request Jun 24, 2021

Use semantic markup in flyout readthedocs/sphinx_rtd_theme#1164

Open

stsewd mentioned this pull request Jul 6, 2021

CORS problems around API #6154

Closed

humitos mentioned this pull request Sep 29, 2021

✨ NEW: add version switcher pydata/pydata-sphinx-theme#436

Merged

cameel mentioned this pull request Dec 2, 2021

[DOCS] Make Download Section Easier To Find ethereum/solidity#12238

Closed

humitos mentioned this pull request Jun 8, 2022

Put the ReadTheDocs version switcher in the header navbar pydata/pydata-sphinx-theme#705

Open

agjohnson mentioned this pull request Nov 23, 2022

Build: support build time injected logic via generic HTML injection #9063

Closed

6 tasks

humitos mentioned this pull request Dec 12, 2022

Make our documentation page APIs more user friendly #7748

Closed

humitos mentioned this pull request Mar 10, 2023

Hosting: manual integrations via build contract #10127

Merged

Update the warning note to be merged

ab62f42

humitos requested a review from a team as a code owner June 21, 2023 13:49

humitos requested a review from benjaoming June 21, 2023 13:49

Merge branch 'main' into davidfischer/flyout-design-doc

d91def7

humitos enabled auto-merge (squash) June 21, 2023 13:50

humitos approved these changes Jun 21, 2023

View reviewed changes

humitos merged commit 463e106 into main Jun 21, 2023

humitos deleted the davidfischer/flyout-design-doc branch June 21, 2023 14:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Flyout and Footer API design document #8052

Flyout and Footer API design document #8052

davidfischer commented Mar 25, 2021 •

edited by humitos

Loading

stsewd Mar 26, 2021

davidfischer Mar 26, 2021

stsewd Mar 26, 2021

ericholscher Mar 30, 2021

stsewd Mar 26, 2021

davidfischer Mar 26, 2021

humitos left a comment

humitos Mar 29, 2021

humitos Mar 29, 2021

ericholscher Mar 30, 2021

agjohnson Apr 1, 2021

ericholscher left a comment

ericholscher Mar 30, 2021

ericholscher Mar 30, 2021

agjohnson left a comment

agjohnson Apr 1, 2021

agjohnson Apr 1, 2021

agjohnson Apr 1, 2021

stale bot commented Jun 2, 2021

humitos commented Jun 13, 2023

agjohnson commented Jun 13, 2023

humitos commented Jun 21, 2023

humitos left a comment



		Overlap with existing API endpoints
		-----------------------------------

		Currently, there are separate API endpoints for translations and downloads,
		but ideally all the data needed to generate a version selector would be available from a single API.

Flyout and Footer API design document #8052

Flyout and Footer API design document #8052

Conversation

davidfischer commented Mar 25, 2021 • edited by humitos Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stale bot commented Jun 2, 2021

humitos commented Jun 13, 2023

agjohnson commented Jun 13, 2023

humitos commented Jun 21, 2023

humitos left a comment

Choose a reason for hiding this comment

davidfischer commented Mar 25, 2021 •

edited by humitos

Loading