Make our documentation page APIs more user friendly

[ericholscher]

This issue is a bit of a meta issue, but it also has at least one concrete action associated with it.

The high level

We want to make it easier for theme authors to integrate the information in our flyout into their themes, which means giving hooks into the information. The most commonly used data here is:

• Active versions
• Translations
• Downloads (PDF, HTML, Epub)
• View/Edit on GitHub links

Short term work

The most obvious place to focus in the short term is breaking out our monolithic "footer API" into something more usable by users. Currently this API returns rendered HTML with the data instead, along with a few additional JSON details. It doesn't include in JSON the actual data used to render the HTML.

So I imagine the steps towards transition are:

• Add additional JSON data to the current response
• Migrate our code to use this new JSON data structure
• Remove the existing HTML data structure after a deprecation period

I don't believe many users are currently using this structure, but I do know some people have custom CSS on top of it, so we should try and not alter the final HTML output if we can avoid it.

Current response

Current flyout

Longer term vision

Once we are returning the JSON data, we need to find a pattern for theme authors to "hook" into this data with Javascript. I think there are a few different approaches to this, and I don't know what the best option would be. I just want to note that is probably the "v2" after we migrate to using the JSON data approach is actually exposing that data to users in a standard way.

Refs #7732

[humitos]

I'm commenting on this issue to bump it up in your inboxes since it may be a good addition to 2023 roadmap.

This issue is also related to:

• Flyout and Footer API design document #8052
• Build: support build time injected logic via generic HTML injection #9063
• Add an explicit flyout placement option #9357

[ericholscher]

Yea, this is definitely defining the problem pretty effectively, thanks for digging it up :)

[humitos]

We've done a lot of work to achieve this goal while working on the new readthedocs-client at https://github.com/readthedocs/readthedocs-client.

Besides, we already have that new API endpoint that eventually we will be expose to users (#10216)

Once we are returning the JSON data, we need to find a pattern for theme authors to "hook" into this data with Javascript

We have an issue opened for this at readthedocs/addons#13

I think we can close this issue here and continue working on the js client repository, since we are discussing there how people will override the specific sections of the flyout, all of it, or just disable it to build their own by using the new API endpoint.

Feel free to re-open if you consider there are still work required to do on this issue.