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:

../../_images/sphinx-hoverxref-example.png

Tooltip shown when hovering on a reference using sphinx-hoverxref.

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.

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.