From d9c4bb7b860aa5d12c21bebaf10e3e20a4400572 Mon Sep 17 00:00:00 2001
From: Manuel Kaufmann <humitos@gmail.com>
Date: Wed, 6 Oct 2021 13:58:49 +0200
Subject: [PATCH 1/3] EmbedAPIv3: docs for endpoint and guide updated

---
 docs/api/v3.rst                   | 39 +++++++++++++++++++++++++++++++
 docs/guides/embedding-content.rst | 29 ++++++++++-------------
 readthedocs/embed/v3/views.py     |  2 +-
 3 files changed, 52 insertions(+), 18 deletions(-)

diff --git a/docs/api/v3.rst b/docs/api/v3.rst
index 6c42647ab96..ad56ca16d85 100644
--- a/docs/api/v3.rst
+++ b/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
 ---------------
 
diff --git a/docs/guides/embedding-content.rst b/docs/guides/embedding-content.rst
index 3ce97910fb9..9207d0f3026 100644
--- a/docs/guides/embedding-content.rst
+++ b/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::
 
diff --git a/readthedocs/embed/v3/views.py b/readthedocs/embed/v3/views.py
index 62a5f690743..86f86b67764 100644
--- a/readthedocs/embed/v3/views.py
+++ b/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
 

From e7315aaf8d5183bca9aea12ff1f9cf0a9fa89333 Mon Sep 17 00:00:00 2001
From: Manuel Kaufmann <humitos@gmail.com>
Date: Wed, 13 Oct 2021 07:46:51 +0200
Subject: [PATCH 2/3] Update docs/api/v3.rst

Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
---
 docs/api/v3.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api/v3.rst b/docs/api/v3.rst
index ad56ca16d85..ee8998f15e5 100644
--- a/docs/api/v3.rst
+++ b/docs/api/v3.rst
@@ -1861,7 +1861,7 @@ Embed
 
     .. note::
 
-       Passing ``?doctool=`` and ``?doctoolversion=`` may make the response to behave better,
+       Passing ``?doctool=`` and ``?doctoolversion=`` may improve the response,
        since the endpoint will know more about the exact structure of the HTML and can make better decisions.
 
 

From 3cd423b7f2e81d02abd4f70d75e7a71c7b799f35 Mon Sep 17 00:00:00 2001
From: Manuel Kaufmann <humitos@gmail.com>
Date: Wed, 13 Oct 2021 07:54:10 +0200
Subject: [PATCH 3/3] Feedback from review

---
 docs/api/v3.rst                   | 3 ++-
 docs/guides/embedding-content.rst | 4 ++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/api/v3.rst b/docs/api/v3.rst
index ee8998f15e5..aaeb0bacc63 100644
--- a/docs/api/v3.rst
+++ b/docs/api/v3.rst
@@ -1832,6 +1832,7 @@ Embed
 .. http:get::  /api/v3/embed/
 
     Retrieve HTML-formatted content from documentation page or section.
+    Read :doc:`guides/embedding-content` to know more about how to use this endpoint.
 
     **Example request**:
 
@@ -1856,7 +1857,7 @@ Embed
     :>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 doctool: *optional* documentation tool key name used to generate the target documentation (currently, only ``sphinx`` is accepted)
     :query string doctoolversion: *optional* documentation tool version used to generate the target documentation (e.g. ``4.2.0``).
 
     .. note::
diff --git a/docs/guides/embedding-content.rst b/docs/guides/embedding-content.rst
index 9207d0f3026..e2f090bb6af 100644
--- a/docs/guides/embedding-content.rst
+++ b/docs/guides/embedding-content.rst
@@ -59,8 +59,8 @@ from our own docs and will populate the content of it into the ``#help-container
     <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',
+      // 'doctool': 'sphinx',
+      // 'doctoolversion': '4.2.0',
     };
     var url = 'https://readthedocs.org/api/v3/embed/?' + $.param(params);
     $.get(url, function(data) {