Merge pull request #146 from readthedocs/humitos/embed-api-v3

Author: humitos

.readthedocs.yml

@@ -1,7 +1,7 @@
 version: 2
 
 python:
-  version: 3
+  version: "3.8"
   install:
     - method: pip
       path: .

docs/conf.py

@@ -55,10 +55,16 @@
 intersphinx_mapping = {
     'readthedocs': ('https://docs.readthedocs.io/en/stable/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'sympy': ('https://docs.sympy.org/latest/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'python': ('https://docs.python.org/3/', None),
 }
 hoverxref_intersphinx = [
     'readthedocs',
     'sphinx',
+    'sympy',
+    'numpy',
+    'python',
 ]
 hoverxref_intersphinx_types = {
     'readthedocs': 'modal',
@@ -81,6 +87,10 @@
     # Building on a local Read the Docs instance
     hoverxref_api_host = 'http://community.dev.readthedocs.io'
 
+if os.environ.get('NGROK_READTHEDOCS') == 'True':
+    # Building on a local Read the Docs instance using NGROK for HTTPS
+    hoverxref_api_host = 'https://readthedocs.ngrok.io'
+
 hoverxref_tooltip_maxwidth = 650
 hoverxref_auto_ref = True
 hoverxref_roles = [
@@ -93,6 +103,7 @@
     'confval': 'tooltip',
     'mod': 'modal',
     'class': 'modal',
+    'obj': 'tooltip',
 }
 hoverxref_domains = [
     'py',

docs/configuration.rst

@@ -101,8 +101,9 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
    .. warning::
 
-      The Sphinx's target project **must be hosted on Read the Docs** to work.
-      This is a current limitation that we hope to remove in the future.
+      The Sphinx's target project **must be hosted on Read the Docs** to work or,
+      be one of the allowed external projects:
+      currently CPython, SymPy, NumPy are supported.
 
 .. confval:: hoverxref_intersphinx_types
 
@@ -152,33 +153,16 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 .. _Mathjax: http://www.sphinx-doc.org/es/master/usage/extensions/math.html#module-sphinx.ext.mathjax
 
 
-.. warning::
-
-   You shouldn't modify the following three settings (api_host, project, version) unless you know what you are doing.
-   Their defaults should be fine to build the documentation and make it work in Read the Docs.
-
-
 .. confval:: hoverxref_api_host
 
    Description: Host URL for the API to retrieve the content of the floating window
 
-   Default: ``https://readthedocs.org``
-
-   Type: string
-
-.. confval:: hoverxref_project
-
-   Description: Read the Docs project slug
-
-   Default: It defaults to ``READTHEDOCS_PROJECT`` environment variable
-
-   Type: string
-
-.. confval:: hoverxref_version
+   .. warning::
 
-   Description: Read the Docs version slug
+     You shouldn't modify this setting unless you know what you are doing.
+     Its default should be fine to build the documentation and make it work in Read the Docs.
 
-   Default: It defaults to ``READTHEDOCS_VERSION`` environment variable
+   Default: ``https://readthedocs.org``
 
    Type: string
 

docs/development.rst

@@ -21,13 +21,11 @@ To setup this approach, you need to put these settings in the ``conf.py`` of you
 
 .. code-block:: python
 
-   hoverxref_project = 'sphinx-hoverxref'
-   hoverxref_version = 'latest'
    hoverxref_api_host = 'https://readthedocs.org'
 
 After building the documentation all the requests will be done to URLs like::
 
-  https://readthedocs.org/api/v2/embed/?project=sphinx-hoverxref&version=latest&doc=...&section=...
+  https://readthedocs.org/api/v3/embed/?doctool=sphinx&doctoolversion=...&url=...
 
 .. note::
 
@@ -84,7 +82,7 @@ To make the extension to work, you will need to define this setting in your ``co
 
 .. code-block:: python
 
-   hoverxref_api_host = 'http://dev.readthedocs.io:8000'
+   hoverxref_api_host = 'http://community.dev.readthedocs.io'
 
 .. tip::
 

docs/index.rst

@@ -99,8 +99,8 @@ Badges:
 .. _Read the Docs: https://readthedocs.org
 
 
-.. |Build| image:: https://travis-ci.org/readthedocs/sphinx-hoverxref.svg?branch=master
-   :target: https://travis-ci.org/readthedocs/sphinx-hoverxref
+.. |Build| image:: https://circleci.com/gh/readthedocs/sphinx-hoverxref.svg?style=svg
+   :target: https://circleci.com/gh/readthedocs/sphinx-hoverxref
    :alt: Build status
 .. |PyPI version| image:: https://img.shields.io/pypi/v/sphinx-hoverxref.svg
    :target: https://pypi.org/project/sphinx-hoverxref

docs/installation.rst

@@ -37,8 +37,8 @@ you can use ``:hoverxref:`` role to show a tooltip [#]_ when hovering with the m
 .. warning::
 
    This extension **requires a backend server** to retrieve the tooltip content.
-   Currently only `Read the Docs`_ is supported,
-   so it will only work if your documentation is hosted on Read the Docs.
+   Currently, only `Read the Docs`_ is supported as backend server.
+   Take into account that your documentation has to be hosted on Read the Docs for this extension to work.
 
 If you prefer to apply this behavior to *all* your ``:ref:`` in your documentation,
 you can use the config :confval:`hoverxref_auto_ref`.

docs/requirements.txt

@@ -1,12 +1,6 @@
-# Sphinx 3.5.x includes a feature to only include the JS and CSS on the pages
-# that they are used. This conflicts when we render content that uses MathJax,
-# since the page that shows the tooltip does not has MathJax loaded, but the
-# content rendered inside the tooltip requires it to work.
-# https://github.com/sphinx-doc/sphinx/pull/8631
-sphinx==3.4.3  # pyup: <3.5
-
+sphinx==4.2.0
 sphinx-autoapi==1.8.4
-sphinx-rtd-theme==0.5.2
+sphinx-rtd-theme==1.0.0
 sphinx-tabs==3.2.0
 sphinx-prompt==1.4.0
 sphinx-version-warning==1.1.2

docs/usage.rst

@@ -7,9 +7,7 @@ and will embed the content of the document/section the link is pointing to, into
 
 ``:hoverxref:`` role uses Sphinx's internals reference resolution to find out where the link points to.
 So, the way of referencing the section works in the same way as the ``:ref:`` standard role.
-See `Sphinx's ref role documentation`_ for more information.
-
-.. _Sphinx's ref role documentation: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations
+See Sphinx's :rst:role:`ref` for more information.
 
 Simplest usage example,
 
@@ -42,14 +40,23 @@ Show a tooltip for :doc:`Read the Docs automation rules <readthedocs:automation-
 
 .. note::
 
-   Keep in mind that the linked project should be hosted at Read the Docs.
-   This is a limitation that will be removed in the future.
+   Keep in mind that the linked project should be hosted at Read the Docs or,
+   be one of the allowed external projects:
+   currently CPython, SymPy, NumPy are supported.
+
+
+Example with projects not hosted on Read the Docs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Show a tooltip for CPython documentation: :py:mod:`webbrowser <webbrowser>`.
+* Show a tooltip for SymPy documentation: :py:class:`sympy.functions.combinatorial.numbers.tribonacci <sympy.functions.combinatorial.numbers.tribonacci>`.
+* Show a tooltip for NumPy documentation: :py:class:`numpy.single <numpy.single>`.
 
 
 Tooltip on custom object
 ------------------------
 
-Sphinx has the ability to define custom objects (via `Sphinx.add_object_type`_).
+Sphinx has the ability to define custom objects (via :py:meth:`Sphinx.add_object_type <sphinx.application.Sphinx.add_object_type>`).
 ``hoverxref`` can also show a tooltip on these objects if desired.
 You need to tell ``hoverxref`` which are the roles where the tooltip has to appear on.
 To do this, use :confval:`hoverxref_roles <hoverxref_roles>` config.
@@ -119,9 +126,9 @@ These actions are usually calling a Javascript function.
 
 .. warning::
 
-   Note that Sphinx>3.5 adds `a feature to only include JS/CSS in pages where they are used`_ instead of in all the pages.
+   Note that Sphinx>=3.5 adds `a feature to only include JS/CSS in pages where they are used`_ instead of in all the pages.
    This `may affect the rendering of tooltips`_ that includes content requiring extra rendering steps.
-   **Make sure you are using Sphinx 3.4.x or >=4.1.x** if you require rendering this type of content in your tooltips.
+   **Make sure you are using Sphinx <=3.4.x or >=4.1.x** if you require rendering this type of content in your tooltips.
 
    .. _a feature to only include JS/CSS in pages where they are used: https://github.com/sphinx-doc/sphinx/pull/8631
    .. _may affect the rendering of tooltips: https://github.com/sphinx-doc/sphinx/issues/9115
@@ -151,8 +158,6 @@ To render a tooltip where its contents has a ``mathjax`` you need to enable :con
 Show a :hoverxref:`tooltip with Mathjax <mathjax:Mathjax>` formulas.
 
 
-.. _Sphinx.add_object_type: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_object_type
-
 .. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
 .. _mathjax: http://www.sphinx-doc.org/es/master/usage/extensions/math.html#module-sphinx.ext.mathjax
 

hoverxref/_static/js/hoverxref.js_t

@@ -79,22 +79,14 @@ function reLoadSphinxTabs() {
     };
 };
 
-function getEmbedURL(project, version, doc, docpath, section, url) {
-    if (url) {
-        var params = {
-            'url': url,
-        }
-    } else {
-        var params = {
-            'project': project,
-            'version': version,
-            'doc': doc,
-            'path': docpath,
-            'section': section,
-        }
+function getEmbedURL(url) {
+    var params = {
+        'doctool': 'sphinx',
+        'doctoolversion': '{{ hoverxref_sphinx_version }}',
+        'url': url,
     }
     console.debug('Data: ' + JSON.stringify(params));
-    var url = '{{ hoverxref_api_host }}' + '/api/v2/embed/?' + $.param(params);
+    var url = '{{ hoverxref_api_host }}' + '/api/v3/embed/?' + $.param(params);
     console.debug('URL: ' + url);
     return url
 }
@@ -109,20 +101,15 @@ $(document).ready(function() {
         animationDuration: {{ hoverxref_tooltip_animation_duration }},
         side: '{{ hoverxref_tooltip_side }}',
         content: '{{ hoverxref_tooltip_content }}',
+        contentAsHTML: true,
 
         functionBefore: function(instance, helper) {
             var $origin = $(helper.origin);
-            var project = $origin.data('project');
-            var version = $origin.data('version');
-            var doc = $origin.data('doc');
-            var docpath = $origin.data('docpath');
-            var section = $origin.data('section');
-            var url = $origin.data('url');
-
+            var href = $origin.prop('href');
 
             // we set a variable so the data is only loaded once via Ajax, not every time the tooltip opens
             if ($origin.data('loaded') !== true) {
-                var url = getEmbedURL(project, version, doc, docpath, section, url);
+                var url = getEmbedURL(href);
                 $.get(url, function(data) {
                     // call the 'content' method to update the content of our tooltip with the returned data.
                     // note: this content update will trigger an update animation (see the updateAnimation option)
@@ -186,23 +173,21 @@ $(document).ready(function() {
     {% endif %}
 
     function showModal(element) {
-        var project = element.data('project');
-        var version = element.data('version');
-        var doc = element.data('doc');
-        var docpath = element.data('docpath');
-        var section = element.data('section');
-        var url = element.data('url');
-
-        var url = getEmbedURL(project, version, doc, docpath, section, url);
+        var href = element.prop('href');
+        var url = getEmbedURL(href);
         $.get(url, function(data) {
             var content = $('<div></div>');
-            content.html(data['content'][0]);
+            content.html(data['content']);
 
             var h1 = $('h1:first', content);
             var title = h1.text()
             if (title) {
                 var link = $('a', h1).attr('href') || '#';
-                var a = $('<a></a>').attr('href', link).text('{{ hoverxref_modal_prefix_title }}' + title.replace('¶', ''));
+
+                // Remove permalink icon from the title
+                var title = title.replace('¶', '').replace('', '');
+
+                var a = $('<a></a>').attr('href', link).text('{{ hoverxref_modal_prefix_title }}' + title);
             }
             else {
                 var a = '{{ hoverxref_modal_prefix_title }}{{ hoverxref_modal_default_title }}';