Embed APIv3: use latest embed API version

docs/conf.py

@@ -69,9 +69,6 @@
 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
@@ -90,8 +87,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'
+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

docs/configuration.rst

@@ -153,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/usage.rst

@@ -7,7 +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 :ref:`Sphinx's ref role documentation <sphinx:ref-role>` for more information.
+See Sphinx's :rst:role:`ref` for more information.
 
 Simplest usage example,
 

hoverxref/_static/js/hoverxref.js_t

@@ -105,14 +105,11 @@ $(document).ready(function() {
 
         functionBefore: function(instance, helper) {
             var $origin = $(helper.origin);
-            // 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');
-
+            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(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)
@@ -176,10 +173,8 @@ $(document).ready(function() {
     {% endif %}
 
     function showModal(element) {
-        // 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);
+        var href = element.prop('href');
+        var url = getEmbedURL(href);
         $.get(url, function(data) {
             var content = $('<div></div>');
             content.html(data['content']);

hoverxref/domains.py

@@ -1,5 +1,4 @@
 from sphinx.util import logging
-from .utils import get_ref_xref_data, get_ref_obj_data, get_ref_numref_data
 
 logger = logging.getLogger(__name__)
 
@@ -12,7 +11,7 @@ class HoverXRefBaseDomain:
         'hoverxrefmodal',
     )
 
-    def _inject_hoverxref_data(self, env, refnode, typ, docname, docpath, labelid):
+    def _inject_hoverxref_data(self, env, refnode, typ):
         classes = ['hoverxref']
         type_class = None
         if typ == 'hoverxreftooltip':
@@ -35,33 +34,12 @@ def _inject_hoverxref_data(self, env, refnode, typ, docname, docpath, labelid):
             classes.append(type_class)
 
         refnode.replace_attr('classes', classes)
-
-        project = env.config.hoverxref_project
-        version = env.config.hoverxref_version
-        refnode._hoverxref = {
-            'data-project': project,
-            'data-version': version,
-            'data-doc': docname,
-            '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)
-        docpath = docpath.replace(builder.outdir, '')
-        return docpath
+        # TODO: log something else here, so we can unique identify this node
+        logger.debug(
+            ':%s: _hoverxref injected. classes=%s',
+            typ,
+            classes,
+        )
 
     def _is_ignored_ref(self, env, target):
         # HACK: skip all references if the builder is non-html. We shouldn't
@@ -90,27 +68,10 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         if refnode is None:
             return refnode
 
-        if any([
-                not env.config.hoverxref_is_configured,
-                self._is_ignored_ref(env, target),
-        ]):
+        if self._is_ignored_ref(env, target):
             return refnode
 
-        modname = node.get('py:module')
-        clsname = node.get('py:class')
-        searchmode = node.hasattr('refspecific') and 1 or 0
-        matches = self.find_obj(env, modname, clsname, target,
-                                typ, searchmode)
-        name, obj = matches[0]
-
-        docname, labelid = obj[0], name
-        docpath = self._get_docpath(builder, docname)
-        self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
-        logger.debug(
-            ':ref: _hoverxref injected: fromdocname=%s %s',
-            fromdocname,
-            refnode._hoverxref,
-        )
+        self._inject_hoverxref_data(env, refnode, typ)
         return refnode
 
 
@@ -122,8 +83,8 @@ class HoverXRefStandardDomainMixin(HoverXRefBaseDomain):
     (``sphinx.addnodes.pending_xref``). These nodes are translated to regular
     ``docsutils.nodes.reference`` for this domain class.
 
-    Before loosing the data used to resolve the reference, our customized domain
-    saves it inside the node itself to be used later by the ``HTMLTranslator``.
+    This class add the required ``hoverxref`` and ``modal``/``tooltip`` to tell
+    the frontend to show a modal/tooltip on this element.
     """
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
@@ -140,21 +101,13 @@ def _resolve_ref_xref(self, env, fromdocname, builder, typ, target, node, contno
             return refnode
 
         if any([
-                not env.config.hoverxref_is_configured,
                 self._is_ignored_ref(env, target),
                 not (env.config.hoverxref_auto_ref or typ in self.hoverxref_types)
         ]):
             return refnode
 
 
-        docname, labelid, _ = get_ref_xref_data(self, node, target)
-        docpath = self._get_docpath(builder, docname)
-        self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
-        logger.debug(
-            ':ref: _hoverxref injected: fromdocname=%s %s',
-            fromdocname,
-            refnode._hoverxref,
-        )
+        self._inject_hoverxref_data(env, refnode, typ)
         return refnode
 
     def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contnode):
@@ -163,21 +116,12 @@ def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contno
             return refnode
 
         if any([
-                not env.config.hoverxref_is_configured,
                 self._is_ignored_ref(env, target),
                 typ not in env.config.hoverxref_roles,
         ]):
             return refnode
 
-        docname, labelid = get_ref_obj_data(self, node, typ, target)
-        docpath = self._get_docpath(builder, docname)
-        self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
-        logger.debug(
-            ':%s: _hoverxref injected: fromdocname=%s %s',
-            typ,
-            fromdocname,
-            refnode._hoverxref,
-        )
+        self._inject_hoverxref_data(env, refnode, typ)
         return refnode
 
     # TODO: combine this method with ``_resolve_obj_xref``
@@ -187,19 +131,10 @@ def _resolve_numref_xref(self, env, fromdocname, builder, typ, target, node, con
             return refnode
 
         if any([
-                not env.config.hoverxref_is_configured,
                 self._is_ignored_ref(env, target),
                 typ not in env.config.hoverxref_roles,
         ]):
             return refnode
 
-        docname, labelid = get_ref_numref_data(self, node, typ, target)
-        docpath = self._get_docpath(builder, docname)
-        self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
-        logger.debug(
-            ':%s: _hoverxref injected: fromdocname=%s %s',
-            typ,
-            fromdocname,
-            refnode._hoverxref,
-        )
+        self._inject_hoverxref_data(env, refnode, typ)
         return refnode