|
| 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§ion=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. |
0 commit comments