Embed APIv3: use latest embed API version

.readthedocs.yml

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

docs/conf.py

@@ -55,14 +55,23 @@
 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',
     'sphinx': 'tooltip',
+    'sympy': 'tooltip',
+    'numpy': 'tooltip',
+    'python': 'tooltip',
 }
 
 # Used when building the documentation from the terminal and using a local Read
@@ -81,6 +90,9 @@
     # Building on a local Read the Docs instance
     hoverxref_api_host = 'http://community.dev.readthedocs.io'
 
+# TODO: remove me when EmbedAPIv3 gets deployed in production
+hoverxref_api_host = 'https://readthedocs.ngrok.io'
+
 hoverxref_tooltip_maxwidth = 650
 hoverxref_auto_ref = True
 hoverxref_roles = [
@@ -93,6 +105,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
 

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 :ref:`Sphinx's ref role documentation <sphinx:ref-role>` 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,18 @@ $(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');
+            // TODO: we are failing on some elements to set the URL from the
+            // backend, but we can use `href` instead.
+            var url = $origin.data('url') || $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(url);
                 $.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 +176,23 @@ $(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);
+        // TODO: we are failing on some elements to set the URL from the
+        // backend, but we can use `href` instead.
+        var url = element.data('url') || element.prop('href');
+        var url = getEmbedURL(url);
         $.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 }}';

hoverxref/domains.py

@@ -45,6 +45,18 @@ def _inject_hoverxref_data(self, env, refnode, typ, docname, docpath, labelid):
             'data-docpath': docpath,
             'data-section': labelid,
         }
+        url = refnode.get('refuri')
+        if url:
+            refnode._hoverxref.update({
+                # FIXME: data-url requires to use the full URL here. At this
+                # point, we need to know the domain where the project is hosted
+                'data-url': f'https://sphinx-hoverxref--146.org.readthedocs.build/en/146/{url}',
+            })
+        else:
+            logger.info(
+                'refuri not found for node. node=%s',
+                refnode.__dict__,
+            )
 
     def _get_docpath(self, builder, docname):
         docpath = builder.get_outfilename(docname)

hoverxref/extension.py

@@ -222,9 +222,20 @@ def missing_reference(app, env, node, contnode):
         #   refexplicit: False
         inventories = InventoryAdapter(env)
 
+        # TODO: credits to https://github.com/readthedocs/sphinx-hoverxref/pull/144
+        # This chunk of code needs tests :)
+        reftype_fallbacks = {
+            'meth': 'method',
+            'mod': 'module',
+        }
+
         for inventory_name in app.config.hoverxref_intersphinx:
             inventory = inventories.named_inventory.get(inventory_name, {})
-            if inventory.get(f'{domain}:{reftype}', {}).get(target) is not None:
+            inventory_member = (
+                inventory.get(f'{domain}:{reftype}') or
+                inventory.get(f'{domain}:{reftype_fallbacks.get(reftype)}')
+            )
+            if inventory_member and inventory_member.get(target) is not None:
                 # The object **does** exist on the inventories defined by the
                 # user: enable hoverxref on this node
                 skip_node = False
@@ -376,6 +387,7 @@ def setup(app):
     app.add_config_value('hoverxref_intersphinx', [], 'env')
     app.add_config_value('hoverxref_intersphinx_types', {}, 'env')
     app.add_config_value('hoverxref_api_host', 'https://readthedocs.org', 'env')
+    app.add_config_value('hoverxref_sphinx_version', sphinx.__version__, 'env')
 
     # Tooltipster settings
     # Deprecated in favor of ``hoverxref_api_host``