EmbedAPIv3: docs for endpoint and guide updated

docs/api/v3.rst

@@ -1826,6 +1826,45 @@ Remote Repository listing
     :requestheader Authorization: token to authenticate.
 
 
+Embed
+-----
+
+.. http:get::  /api/v3/embed/
+
+    Retrieve HTML-formatted content from documentation page or section.
+
+    **Example request**:
+
+    .. prompt:: bash $
+
+        curl https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23read-the-docs-features
+
+    **Example response**:
+
+    .. sourcecode:: js
+
+       {
+           "url": "https://docs.readthedocs.io/en/latest/features.html#read-the-docs-features",
+           "fragment": "read-the-docs-features",
+           "content": "<div class=\"section\" id=\"read-the-docs-features\">\n<h1>Read the Docs ...",
+           "external": false
+       }
+
+    :>json string url: URL of the document.
+    :>json string fragment: fragmet part of the URL used to query the page.
+    :>json string content: HTML content of the section.
+    :>json string external: whether or not the page is hosted on Read the Docs or externally.
+
+    :query string url: full URL of the document (with optional fragment) to fetch content from.
+    :query string doctool: *optional* documentation tool key name used to generate the target documentation (e.g. ``sphinx``)
+    :query string doctoolversion: *optional* documentation tool version used to generate the target documentation (e.g. ``4.2.0``).
+
+    .. note::
+
+       Passing ``?doctool=`` and ``?doctoolversion=`` may make the response to behave better,
+       since the endpoint will know more about the exact structure of the HTML and can make better decisions.
+
+
 Additional APIs
 ---------------
 

docs/guides/embedding-content.rst

@@ -1,7 +1,8 @@
 Embedding Content From Your Documentation
 =========================================
 
-Read the Docs allows you to embed content from any of the projects we host.
+Read the Docs allows you to embed content from any of the projects we host and specific allowed external domains
+(currently, :djangosetting:`RTD_EMBED_API_EXTERNAL_DOMAINS`)
 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,
@@ -57,12 +58,11 @@ from our own docs and will populate the content of it into the ``#help-container
 
     <script type="text/javascript">
     var params = {
-      'project': 'docs',
-      'version': 'stable',
-      'doc': 'automation-rules',
-      'section': 'creating-an-automation-rule',
+      '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/v2/embed/?' + $.param(params);
+    var url = 'https://readthedocs.org/api/v3/embed/?' + $.param(params);
     $.get(url, function(data) {
       $('#help-container').content(data['content']);
     });
@@ -102,19 +102,14 @@ and show a modal when the user clicks in a "Help" link.
 Calling the Embed API directly
 ------------------------------
 
-Embed API lives under ``https://readthedocs.org/api/v2/embed/`` URL and accept two different ways of using it:
+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 :ref:`its own documentation <api/v3:embed>` to find out more details.
 
-* passing the exact URL of the section you want to embed
-* sending all the attributes required as GET arguments
+You can click on the following links and check a live response directly in the browser as examples:
 
-The following links return exactly the same response, however the first one passes the ``url`` attribute
-and the second example sends ``project``, ``version``, ``doc``, ``section`` and ``path`` as different attributes.
-You can use the one that works best for your use case.
-
-* https://readthedocs.org/api/v2/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23automatic-documentation-deployment
-* https://readthedocs.org/api/v2/embed/?project=docs&version=latest&doc=features&section=automatic-documentation-deployment&path=features.html
-
-You can click on these links and check the response directly in the browser.
+* https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/stable/features.html%23automatic-documentation-deployment
+* https://readthedocs.org/api/v3/embed/?url=https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html%23confval-hoverxref_role_types&doctool=sphinx&doctoolversion=4.2.0
+* https://readthedocs.org/api/v3/embed/?url=https://docs.sympy.org/latest/tutorial/gotchas.html%23equals-signs
 
 .. note::
 

readthedocs/embed/v3/views.py

@@ -43,7 +43,7 @@ class EmbedAPIBase(CachedResponseMixin, APIView):
 
     ### Example
 
-    GET https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23#full-text-search
+    GET https://readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.io/en/latest/features.html%23full-text-search
 
     """  # noqa