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

@@ -81,6 +81,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 +96,7 @@
     'confval': 'tooltip',
     'mod': 'modal',
     'class': 'modal',
+    'obj': 'tooltip',
 }
 hoverxref_domains = [
     'py',

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

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

@@ -376,6 +376,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``