Embedding Content From Your Documentation¶
Read the Docs allows you to embed content from any of the projects we host. This allows reuse of content across sites, making sure the content is always up to date.
There are a number of uses 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:
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.
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.
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
from our own docs and will populate the content of it into the
#help-container div element.
You can modify this example to subscribe to
and show a modal when the user clicks in a “Help” link.
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.
.. 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
If you change the title it won’t break the embedded content because the label for that title will still be
Please, take a look at the Sphinx
:ref: role documentation for more information about how to create references.
Embed API lives under
https://readthedocs.org/api/v2/embed/ URL and accept two different ways of using it:
- passing the exact URL of the section you want to embed
- sending all the attributes required as GET arguments
The following links return exactly the same response, however the first one passes the
and the second example sends
path as different attributes.
You can use the one that works best for your use case.
You can click on these links and check the response directly in the browser.
All relative links to pages contained in the remote content will continue to point at the remote page.