Expose our Embed tools to users again

[ericholscher]

Currently we have some neat functionality with our Embed API & embed JS client. You can see one version of it here:

https://readthedocs.org/projects/docs/tools/embed/

We have some basic docs for this, but it doesn't document the actual REST API:

• https://docs.readthedocs.io/en/latest/embed.html?highlight=embed
• https://readthedocs.org/api/v1/embed/?project=docs&version=latest&doc=api%2Fv2&section=Build+detail

We should document the actual API, and remove docs around the Sphinx extension, at least. We can work on the Sphinx extension more in the future, but for now I don't think it's quite ready.

Refs #2667 (comment)

Work

• Modernize and clean up client side code
• Release client code in proper way
• Document API
• Remove unused parts of embed for now, target these pieces as later priority

[agjohnson]

I'm +1 on getting this spruced up for release.

I'd also say we probably need to make our client side javascript more polished and user-friendly. I'd like to do a proper release of the client side JS before we promote the embed stuff, especially if the interface in the client side is going to change. I'd rather avoid supporting backwards compatibility with what is essentially POC level client side code.

That repo has sat idle for 4 years, so I'll take some time to delve into it and see what work is needed as a first step there. It's likely that this could be added to our roadmap for the end of this month or next month though, and would be a good feature to be promoting.

[humitos]

We should document the actual API, and remove docs around the Sphinx extension, at least

We already have documented the Embed APIv3 at https://docs.readthedocs.io/en/stable/api/v3.html#embed

I'd also say we probably need to make our client side javascript more polished and user-friendly. I'd like to do a proper release of the client side JS before we promote the embed stuff, especially if the interface in the client side is going to change.

We are re-writing this as an addon now using propper Javascript patterns. We are calling it tooltips addon currently: readthedocs/addons#20