Skip to content

Commit 96140c8

Browse files
authored
Merge pull request #7089 from readthedocs/humitos/embed-docs
Guide for Embed API
2 parents dc12970 + e17f6d8 commit 96140c8

File tree

3 files changed

+96
-0
lines changed

3 files changed

+96
-0
lines changed
Loading

docs/guides/embedding-content.rst

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Embedding Content From Your Documentation
2+
=========================================
3+
4+
Read the Docs allows you to embed content from any of the projects we host.
5+
This allows reuse of content across sites, making sure the content is always up to date.
6+
7+
There are a number of uses cases for embedding content,
8+
so we've built our integration in a way that enables users to build on top of it.
9+
This guide will show you some of our favorite integrations:
10+
11+
.. contents::
12+
:local:
13+
14+
Contextualized tooltips on documentation pages
15+
----------------------------------------------
16+
17+
Tooltips on your own documentation are really useful to add more context to the current page the user is reading.
18+
You can embed any content that is available via reference in Sphinx, including:
19+
20+
* Python object references
21+
* Full documentation pages
22+
* Sphinx references
23+
* Term definitions
24+
25+
We built a Sphinx extension called ``sphinx-hoverxref`` on top of our Embed API
26+
you can install in your project with minimal configuration.
27+
28+
Here is an example showing a tooltip when you hover with the mouse a reference:
29+
30+
.. figure:: /_static/images/guides/sphinx-hoverxref-example.png
31+
:width: 80%
32+
:align: center
33+
34+
Tooltip shown when hovering on a reference using ``sphinx-hoverxref``.
35+
36+
You can find more information about this extension, how to install and configure it in the `hoverxref documentation`_.
37+
38+
.. _hoverxref documentation: https://sphinx-hoverxref.readthedocs.io/
39+
40+
Inline help on application website
41+
----------------------------------
42+
43+
This allows us to keep the official documentation as the single source of truth,
44+
while having great inline help in our application website as well.
45+
On the "Automation Rules" admin page we could embed the content of our :doc:`/automation-rules` documentation
46+
page and be sure it will be always up to date.
47+
48+
.. note::
49+
50+
We recommend you point at tagged releases instead of latest.
51+
Tags don't change over time, so you don't have to worry about the content you are embedding disappearing.
52+
53+
The following example will fetch the section "Creating an automation rule" in page ``automation-rules.html``
54+
from our own docs and will populate the content of it into the ``#help-container`` div element.
55+
56+
.. code-block:: html
57+
58+
<script type="text/javascript">
59+
var params = {
60+
'project': 'docs',
61+
'version': 'stable',
62+
'doc': 'automation-rules',
63+
'section': 'creating-an-automation-rule',
64+
};
65+
var url = 'https://readthedocs.org/api/v2/embed/?' + $.param(params);
66+
$.get(url, function(data) {
67+
$('#help-container').content(data['content']);
68+
});
69+
</script>
70+
71+
<div id="help-container"></div>
72+
73+
You can modify this example to subscribe to ``.onclick`` Javascript event,
74+
and show a modal when the user clicks in a "Help" link.
75+
76+
Calling the Embed API directly
77+
------------------------------
78+
79+
Embed API lives under ``https://readthedocs.org/api/v2/embed/`` URL and accept two different ways of using it:
80+
81+
* passing the exact URL of the section you want to embed
82+
* sending all the attributes required as GET arguments
83+
84+
The following links return exactly the same response, however the first one passes the ``url`` attribute
85+
and the second example sends ``project``, ``version``, ``doc``, ``section`` and ``path`` as different attributes.
86+
You can use the one that works best for your use case.
87+
88+
* https://readthedocs.org/api/v2/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23automatic-documentation-deployment
89+
* https://readthedocs.org/api/v2/embed/?project=docs&version=latest&doc=features&section=automatic-documentation-deployment&path=features.html
90+
91+
You can click on these links and check the response directly in the browser.
92+
93+
.. note::
94+
95+
All relative links to pages contained in the remote content will continue to point at the remote page.

docs/guides/platform.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ These guides will help you customize or tune aspects of Read the Docs.
1616
google-analytics
1717
hiding-a-version
1818
searching-with-readthedocs
19+
embedding-content
1920
specifying-dependencies
2021
technical-docs-seo-guide
2122
wipe-environment

0 commit comments

Comments
 (0)