Permalink
Switch branches/tags
19-upgrade RescueTime-master add-build-signals add-call-to-theme-js admin-icon agj/add-local-dev-docker agj/eslint-repair agj/remove-symlink-serving agj/ssh-add-key agj/test-rel agj/update-translations api-v2-docs auto-import azure backport-style badge-v2 better-search-logging blendify/new_ga break-out-core-urls-views build-pdf-ret-val builder-standards chirathr-webhook_notifications_url_size com-py3-compat davidfischer/cloudflare-ssl-saas davidfischer/document-api-v2 davidfischer/remove-bower davidfischer/storage-epubs-pdfs-zips decoupling-theme-org dont-set-build-state-on-exit embed-integration eric-search-upgrade front-end-standardization gold gthank-master hotfix-confpy-path hotfix-docker-build-bug hotfix-no-stable hotfix-release hotfix-virtualenv-no-downlaod hotfix-virtualenv-no-download hotfix/docker-313-relcorp hotfix/docker-313 hotfix/featureflag-mkdocs-theme hotfix/featureflag-remove-migration hotifx-frontpage-list hotifx-search-linking humitos/admin/crud-env-variables humitos/api/v3 humitos/builds/notify-old-endpoints humitos/clean/fabric-function humitos/cors/allow-api-known-domains humitos/django/compatibility humitos/integrations/handle-error-codes humitos/resolver/username-regex humitos/ssh/management humitos/sshkeys/cryptography humitos/template/override-versions humitos/tests/api humitos/vcs/show-links humitos/versions/clean intersphinx-modeling js-theme-bundle logging-cleanup master migrate-to-autoapi more-gsoc no-sphinx-build-subprocess pr/4577 privacy-backends privacy-filtering programming-language-support project-container-settings project-feature-flip-apiv2 py2-compat py3 rate-limit-builds refactor-builder rel relcorp release/2.5.2 remove-default-role remove-drf-serializer remove-unused-reqs revert-1568-haystack_upgrade revert-search rtd2 santos/implement-extend-install-option search-reapply search-rel search_upgrade simple-symlink-serving spam stale-project-delete-updates symlink-serving team-project-import test-36 theme-0.6.2 theme-version-to-0.4.x token-access tools tox-dependencies upgrade-celery upgrade-sphinx user-dashboard version-tab
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
157 lines (121 sloc) 5.72 KB

Embed API

Read the Docs allow you to embed content from any of the projects we host. This allows for content re-use across sites, making sure the content is always up to date.

Workflow

There are many uses of our Embed API. One of our favorites is for inline help. We have started using this on Read the Docs itself to provide inline help on our main site pages. This allows us to keep the official documentation as the single source of truth, while having great inline help in our application as well.

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.

Note

All relative links to pages contained in the remote content will continue to point at the remote page.

How to use it

Sphinx Extension

You can embed content directly in Sphinx with builds on Read the Docs. We support default configuration variables for your conf.py:

  • readthedocs_embed_project
  • readthedocs_embed_version
  • readthedocs_embed_doc

These are overridable per-call as well. Then you simply use the directive:

# All arguments
.. readthedocs-embed::
    :project: myproject
    :version: latest
    :doc: index
    :section: User Guide

# Or with some defaults
.. readthedocs-embed::
    :doc: index
    :section: User Guide

Javascript

We provide a Javascript library that you can embed on any site. An example:

<!-- In your <head> -->
<link rel="stylesheet" href="http://localhost:5555/static/css/public.css">
<script type="text/javascript" src="http://localhost:5555/static/javascript/bundle-public.js"></script>
<script>
embed = ReadTheDocs.Embed(project, version)
rtd.into('page', 'section', function(content){
    $('#foobar').html(content)
})

</script>

<!-- In your <body> -->
<div id="help_container">
  <a href="#" class="readthedocs-help-embed" data-section="How we envision versions working">(Help)</a>
</div>

This will provide a pop-out for a user with the How we envision versions working section of the versions page. You can see this in action here:



Note

All Read the Docs pages already have the library loaded, so you can ignore the link and first script tags on all documentation.

Warning

We currently do not provide caching on this API. If the remote source you are including changes their page structure or deletes the content, your embed will break.

In Version 2 of this API we will provide a full-formed workflow that will stop this from happening.

Example API Response

Pure API use will return JSON:

{
    "content": [
        "<div class=\"section\" id=\"encoded-data\">\n<h2>Encoded Data?<a class=\"headerlink\" href=\"/docs/requests/en/latest/community/faq.html#encoded-data\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Requests automatically decompresses gzip-encoded responses, and does\nits best to decode response content to unicode when possible.</p>\n<p>You can get direct access to the raw response (and even the socket),\nif needed as well.</p>\n</div>"
    ],
    "wrapped": [
        "\n<div class=\"readthedocs-embed-wrapper\">\n    <div class=\"readthedocs-embed-content\">\n        <div class=\"section\" id=\"encoded-data\">\n<h2>Encoded Data?<a class=\"headerlink\" href=\"/docs/requests/en/latest/community/faq.html#encoded-data\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Requests automatically decompresses gzip-encoded responses, and does\nits best to decode response content to unicode when possible.</p>\n<p>You can get direct access to the raw response (and even the socket),\nif needed as well.</p>\n</div>\n    </div>\n    <div class=\"readthedocs-embed-badge\">\n        Embedded from <a href=\"/docs/requests/en/latest/community/faq.html\">Read the Docs</a>\n    </div>\n</div>\n    "
    ],
    "meta": {
        "project": "requests",
        "doc": "community/faq",
        "section": "Encoded Data?",
        "version": "latest",
        "modified": "Wed, 04 Feb 2015 08:59:59 GMT"
    },
    "url": "/docs/requests/en/latest/community/faq.html",
    "headers": [
        {
            "Frequently Asked Questions": "#"
        },
        {
            "Encoded Data?": "#encoded-data"
        },
        {
            "Custom User-Agents?": "#custom-user-agents"
        },
        {
            "Why not Httplib2?": "#why-not-httplib2"
        },
        {
            "Python 3 Support?": "#python-3-support"
        },
        {
            "What are \u201chostname doesn\u2019t match\u201d errors?": "#what-are-hostname-doesn-t-match-errors"
        }
    ]
}