Announcing Embed API v3 and sphinx-hoverxref 1.0¶
We are thrilled to announce the availability of Read the Docs Embed API v3, along with its official client, sphinx-hoverxref 1.0. This work has been possible in part thanks to the the CZI grant we received.
The value of content embedding¶
As we wrote in our first blog post about sphinx-hoverxref, one of the most powerful features of Sphinx is the possibility of creating cross references to other documentation projects. However, a reader finding several links in a technical documentation might need to open several browser tabs to fully understand the context, resulting in a lot of friction in the form of context switching.
One way of mitigating the problem is to show a small preview in the form of tooltip or modal with the contents of the link. This is where the Embed API and sphinx-hoverxref come in.
Embed API v3 and sphinx-hoverxref 1.0¶
After some months of work, we are excited to publish v3 of our Embed API, and with it, version 1.0 of sphinx-hoverxref.
Among other things, the new versions allow you to embed content from pages hosted outside Read the Docs. For security reasons, we have an allowlist of such external domains that currently includes Python, NumPy, SciPy, SymPy, and we would like to invite the community to suggest more domains to add.
Other additions and fixes include:
Support for JS and CSS assets in Sphinx 4.1+.
Avoid showing the browser built-in tooltip for links that have the extension enabled.
Finally, version 3 of the Embed API paves the way for supporting non-Sphinx projects in the future.
Embedding content with sphinx-hoverxref¶
To use sphinx-hoverxref in your Read the Docs project, declare it as part of your dependencies:
And add it to your list of Sphinx extensions:
extensions = [
# ...other extensions
To enable the extension on all
:ref: of your documentation,
hoverxref_auto_ref = True
And you will start seeing tooltips on your internal references.
:ref: roles, you can also enable tooltips on:
Calling the Embed API directly¶
As explained in our embedding guide, you can call the API directly from any HTTP client:
$ curl -s "https://readthedocs.org/api/v3/embed/\
> %23read-the-docs-features" | python -m json.tool
"content": "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs ...",
Or visually explore the query in the web interface instead.
The reference documentation includes more detail about the parameters and return values of the API.
Try it out!¶
We would like to invite the community to try out these features and send us feedback. With the help of our users, we will keep moving towards a more cohesive documentation ecosystem of interlinked Python projects.
Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!