Skip to content

Commit 837f80a

Browse files
astrojuanluastrojuanlu
authored
Merge pull request #144 from readthedocs/embed-api
Add blog post on Embed API v3
2 parents 348a7c4 + 158e482 commit 837f80a

File tree

2 files changed

+175
-0
lines changed

2 files changed

+175
-0
lines changed

‎conf.py

+4
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,10 @@
252252
'https://jupyterbook.org/',
253253
None
254254
),
255+
'hoverxref': (
256+
'https://sphinx-hoverxref.readthedocs.io/en/stable',
257+
None
258+
),
255259
}
256260

257261
ogp_site_name = "Read the Docs Blog"

‎embed-api-v3.rst

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
.. post:: December 7, 2021
2+
:tags: api, feature, grant
3+
:author: Juan Luis
4+
:location: MAD
5+
6+
.. meta::
7+
:description lang=en:
8+
We are thrilled to announce the availability of Read the Docs Embed API v3,
9+
along with its official client, sphinx-hoverxref 1.0.
10+
We invite the community to try them out and let us know their feedback.
11+
12+
Announcing Embed API v3 and sphinx-hoverxref 1.0
13+
================================================
14+
15+
We are thrilled to announce the availability of Read the Docs Embed API v3,
16+
along with its official client, sphinx-hoverxref 1.0.
17+
This work has been possible in part thanks to the
18+
:doc:`the CZI grant we received </czi-grant-announcement>`.
19+
20+
The value of content embedding
21+
------------------------------
22+
23+
As we wrote in
24+
:doc:`our first blog post about sphinx-hoverxref </hoverxref-intersphinx>`,
25+
one of the most powerful features of Sphinx
26+
is the possibility of creating cross references
27+
to other documentation projects.
28+
However, a reader finding several links in a technical documentation
29+
might need to open several browser tabs to fully understand the context,
30+
resulting in a lot of friction in the form of context switching.
31+
32+
One way of mitigating the problem is to show a small preview
33+
in the form of tooltip or modal with the contents of the link.
34+
This is where the Embed API and sphinx-hoverxref come in.
35+
36+
`sphinx-hoverxref`_ is a Sphinx extension that addresses this problem
37+
by adding tooltips on the cross references of the HTML documentation
38+
with the content of the linked section.
39+
To do so, it inserts a small JavaScript file that
40+
calls the Read the Docs Embed API when the user hovers any link.
41+
:doc:`Back in June </hoverxref-intersphinx>` we announced
42+
intersphinx support in `sphinx-hoverxref`_ 0.6b1,
43+
which allowed users to include modals and tooltips
44+
also for cross references to other projects.
45+
46+
.. figure:: img/sphinx-hoverxref-showcase.gif
47+
:width: 60%
48+
:align: center
49+
:alt: sphinx-hoverxref displaying tooltips for cross references
50+
:target: /_images/sphinx-hoverxref-showcase.gif
51+
52+
sphinx-hoverxref displaying a tooltip including an equation
53+
54+
.. _sphinx-hoverxref: https://sphinx-hoverxref.readthedocs.io/
55+
56+
Some big projects already using it include `Tweepy <https://docs.tweepy.org/>`_,
57+
a Python client for Twitter, and `Scrapy <https://docs.scrapy.org/>`_,
58+
a framework for crawling websites.
59+
60+
Embed API v3 and sphinx-hoverxref 1.0
61+
-------------------------------------
62+
63+
After some months of work, **we are excited to publish v3 of our Embed API,
64+
and with it, version 1.0 of sphinx-hoverxref**.
65+
66+
Among other things,
67+
the new versions allow you to
68+
:ref:`embed content from pages hosted outside Read the Docs <guides/embedding-content:embedding content from your documentation>`.
69+
For security reasons, we have an allowlist of such external domains
70+
that currently includes Python, NumPy, SciPy, SymPy,
71+
and we would like to
72+
`invite the community to suggest more domains to add <https://github.com/readthedocs/readthedocs.org/issues>`_.
73+
74+
Other additions and fixes include:
75+
76+
- Support for JS and CSS assets in Sphinx 4.1+.
77+
- Support for ``glossary`` / ``term`` and sphinxcontrib-bibtex.
78+
- Avoid showing the browser built-in tooltip for links that have the extension enabled.
79+
80+
Finally, version 3 of the Embed API
81+
paves the way for supporting non-Sphinx projects in the future.
82+
83+
Embedding content with sphinx-hoverxref
84+
---------------------------------------
85+
86+
To use sphinx-hoverxref in your Read the Docs project,
87+
:doc:`declare it as part of your dependencies <guides/reproducible-builds>`:
88+
89+
.. code-block::
90+
:caption: requirements.txt
91+
:emphasize-lines: 3
92+
93+
sphinx==4.3.1
94+
sphinx_rtd_theme==1.0.0
95+
sphinx-hoverxref==1.0.0
96+
97+
And add it to your list of Sphinx extensions:
98+
99+
.. code-block::
100+
:caption: conf.py
101+
:emphasize-lines: 3
102+
103+
extensions = [
104+
# ...other extensions
105+
"hoverxref.extension",
106+
]
107+
108+
To enable the extension on all ``:ref:`` of your documentation,
109+
set the ``hoverxref_auto_ref`` to ``True``:
110+
111+
.. code-block::
112+
:caption: conf.py
113+
114+
hoverxref_auto_ref = True
115+
116+
And you will start seeing tooltips on your internal references.
117+
Apart from ``:ref:`` roles, you can also enable tooltips on:
118+
119+
- :ref:`Code objects from any Sphinx domain <hoverxref:Usage:Tooltip on Sphinx Domains>`,
120+
- :ref:`Glossary terms <hoverxref:Usage:Tooltip on glossary terms>`,
121+
- :ref:`BibTeX citations <hoverxref:Usage:Tooltip on sphinxcontrib-bibtex cites>`,
122+
- :ref:`Pages containing extra JavaScript like sphinx-tabs and
123+
MathJax <hoverxref:Usage:Tooltip with content that needs extra rendering steps>`,
124+
- :ref:`Intersphinx references <hoverxref:Usage:Tooltip on intersphinx content>`,
125+
- :ref:`And custom objects! <hoverxref:Usage:Tooltip on custom object>`
126+
127+
.. note::
128+
129+
sphinx-hoverxref includes the JavaScript embed client in the HTML assets,
130+
but it is not yet available as a standalone library that can be reused
131+
with standard frontend packaging tools.
132+
If you would like to see this happening,
133+
`let us know <https://github.com/readthedocs/sphinx-hoverxref/issues/>`_.
134+
135+
Calling the Embed API directly
136+
------------------------------
137+
138+
As explained in :ref:`our embedding
139+
guide <guides/embedding-content:calling the embed api directly>`,
140+
you can call the API directly from any HTTP client:
141+
142+
.. code-block:: console
143+
144+
$ curl -s "https://readthedocs.org/api/v3/embed/\
145+
> ?url=https://docs.readthedocs.io/en/latest/features.html\
146+
> %23read-the-docs-features" | python -m json.tool
147+
{
148+
"url": "https://docs.readthedocs.io/en/latest/features.html#read-the-docs-features",
149+
"fragment": "read-the-docs-features",
150+
"content": "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs ...",
151+
"external": false
152+
}
153+
154+
Or visually explore the query in the `web interface`__ instead.
155+
156+
.. __: https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23read-the-docs-features
157+
158+
The :ref:`reference documentation <readthedocs:api/v3:embed>`
159+
includes more detail about the parameters and return values of the API.
160+
161+
Try it out!
162+
-----------
163+
164+
We would like to invite the community to try out these features and
165+
send us feedback. With the help of our users, we will keep moving towards
166+
a more cohesive documentation ecosystem of interlinked Python projects.
167+
168+
----
169+
170+
Considering using Read the Docs for your next Sphinx or MkDocs project?
171+
Check out `our documentation <https://docs.readthedocs.io/>`_ to get started!

0 commit comments

Comments
 (0)