How to embed content from your documentation
Read the Docs allows you to embed content from any of the projects we host and specific allowed external domains
(currently, docs.python.org
, docs.scipy.org
, docs.sympy.org
, numpy.org
)
This allows reuse of content across sites, making sure the content is always up to date.
There are a number of use cases for embedding content, so we’ve built our integration in a way that enables users to build on top of it. This guide will show you some of our favorite integrations:
Contextualized tooltips on documentation pages
Tooltips on your own documentation are really useful to add more context to the current page the user is reading. You can embed any content that is available via reference in Sphinx, including:
Python object references
Full documentation pages
Sphinx references
Term definitions
We built a Sphinx extension called sphinx-hoverxref
on top of our Embed API
you can install in your project with minimal configuration.
Here is an example showing a tooltip when you hover with the mouse a reference:
You can find more information about this extension, how to install and configure it in the hoverxref documentation.
Inline help on application website
This allows us to keep the official documentation as the single source of truth, while having great inline help in our application website as well. On the “Automation Rules” admin page we could embed the content of our Automation rules documentation page and be sure it will be always up to date.
Note
We recommend you point at tagged releases instead of latest. Tags don’t change over time, so you don’t have to worry about the content you are embedding disappearing.
The following example will fetch the section “Creating an automation rule” in page automation-rules.html
from our own docs and will populate the content of it into the #help-container
div element.
<script type="text/javascript">
var params = {
'url': 'https://docs.readthedocs.io/en/latest/automation-rules.html%23creating-an-automation-rule',
// 'doctool': 'sphinx',
// 'doctoolversion': '4.2.0',
};
var url = 'https://readthedocs.org/api/v3/embed/?' + $.param(params);
$.get(url, function(data) {
$('#help-container').content(data['content']);
});
</script>
<div id="help-container"></div>
You can modify this example to subscribe to .onclick
Javascript event,
and show a modal when the user clicks in a “Help” link.
Tip
Take into account that if the title changes, your section
argument will break.
To avoid that, you can manually define Sphinx references above the sections you don’t want to break.
For example,
.. in your .rst document file
.. _unbreakable-section-reference:
Creating an automation rule
---------------------------
This is the text of the section.
.. in your .md document file
(unbreakable-section-reference)=
## Creating an automation rule
This is the text of the section.
To link to the section “Creating an automation rule” you can send section=unbreakable-section-reference
.
If you change the title it won’t break the embedded content because the label for that title will still be unbreakable-section-reference
.
Please, take a look at the Sphinx :ref:
role documentation for more information about how to create references.
Calling the Embed API directly
Embed API lives under https://readthedocs.org/api/v3/embed/
URL and accept the URL of the content you want to embed.
Take a look at its own documentation to find out more details.
You can click on the following links and check a live response directly in the browser as examples:
Note
All relative links to pages contained in the remote content will continue to point at the remote page.