Merge pull request #86 from readthedocs/humitos/support-intersphinx

Author: humitos

.readthedocs.yml

@@ -9,5 +9,6 @@ python:
 
 sphinx:
   configuration: docs/conf.py
-  
+  fail_on_warning: true
+
 formats: []

docs/conf.py

@@ -13,14 +13,16 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import datetime
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'sphinx-hoverxref'
-copyright = '2019, Manuel Kaufmann'
+year = datetime.datetime.now().year
+copyright = f'{year}, Manuel Kaufmann'
 author = 'Manuel Kaufmann'
 
 # The short X.Y version
@@ -39,6 +41,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.intersphinx',
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.mathjax',
     'sphinx_tabs.tabs',
@@ -49,6 +52,19 @@
     'notfound.extension',
 ]
 
+intersphinx_mapping = {
+    'readthedocs': ('https://docs.readthedocs.io/en/stable/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+hoverxref_intersphinx = [
+    'readthedocs',
+    'sphinx',
+]
+hoverxref_intersphinx_types = {
+    'readthedocs': 'modal',
+    'sphinx': 'tooltip',
+}
+
 # Used when building the documentation from the terminal and using a local Read
 # the Docs instance as backend
 hoverxref_api_host = 'http://localhost:8000'

docs/configuration.rst

@@ -91,10 +91,49 @@ These settings are global and have effect on both, tooltips and modal dialogues.
           'setting',
       ]
 
+.. confval:: hoverxref_intersphinx
+
+   Description: Enable Sphinx's hoverxref extension on intersphinx targets from ``intersphinx_mapping``.
+
+   Default: ``[]``
+
+   Type: list
+
+   .. 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.
+
+.. confval:: hoverxref_intersphinx_types
+
+   Description: Style used for intersphinx links.
+
+   Default: ``{}``. It uses :confval:`hoverxref_default_type` if the intersphinx target is not defined in this config.
+
+   Type: dict
+
+   Example:
+
+   .. code-block:: python
+
+      {
+          # make specific links to use a particular tooltip type
+          'readthdocs': {
+              'doc': 'modal',
+              'ref': 'tooltip',
+          },
+          'python': {
+              'class': 'modal',
+              'ref':, 'tooltip',
+          },
+
+          # make all links for Sphinx to be ``tooltip``
+          'sphinx': 'tooltip',
+      }
 
 .. confval:: hoverxref_sphinxtabs
 
-   Description: trigger an extra step to render tooltips where its content has a `Sphinx Tabs`_
+   Description: Trigger an extra step to render tooltips where its content has a `Sphinx Tabs`_
 
    Default: ``False``
 
@@ -104,7 +143,7 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
 .. confval:: hoverxref_mathjax
 
-   Description: trigger an extra step to render tooltips where its content has a `Mathjax`_
+   Description: Trigger an extra step to render tooltips where its content has a `Mathjax`_
 
    Default: ``False``
 

docs/usage.rst

@@ -22,6 +22,30 @@ will render to this:
 This will :hoverxref:`show a tooltip <hoverxref:hoverxref>` in the linked words to ``hoverxref``.
 
 
+Tooltip on intersphinx content
+------------------------------
+
+Sphinx comes with a nice built-in extension called :doc:`sphinx.ext.intersphinx <sphinx:usage/extensions/intersphinx>`
+that allows you to generate links to specific objects in other project's documentation pages.
+
+You can combine this extension with ``sphinx-hoverxref`` to show tooltips over these links to other projects.
+For example, this documentation itself configures intersphinx with Read the Docs documentation and allow us
+to do the following:
+
+.. code-block:: rst
+
+   Show a tooltip for :doc:`Read the Docs automation rules <readthedocs:automation-rules>`.
+
+That will render to:
+
+Show a tooltip for :doc:`Read the Docs automation rules <readthedocs:automation-rules>`.
+
+.. 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.
+
+
 Tooltip on custom object
 ------------------------
 
@@ -99,7 +123,7 @@ These actions are usually calling a Javascript function.
    This `may affect the rendering of tooltips`_ that includes content requiring extra rendering steps.
    **Make sure you are using Sphinx 3.4.x** if you require rendering this type of content in your tooltips.
 
-   .. _a feature to only include JS/CS in pages where they are used: https://github.com/sphinx-doc/sphinx/pull/8631
+   .. _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
 
 

hoverxref/_static/js/hoverxref.js_t

@@ -79,13 +79,19 @@ function reLoadSphinxTabs() {
     };
 };
 
-function getEmbedURL(project, version, doc, docpath, section) {
-    var params = {
-        'project': project,
-        'version': version,
-        'doc': doc,
-        'path': docpath,
-        'section': section,
+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,
+        }
     }
     console.debug('Data: ' + JSON.stringify(params));
     var url = '{{ hoverxref_api_host }}' + '/api/v2/embed/?' + $.param(params);
@@ -111,11 +117,12 @@ $(document).ready(function() {
             var doc = $origin.data('doc');
             var docpath = $origin.data('docpath');
             var section = $origin.data('section');
+            var url = $origin.data('url');
 
 
             // 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);
+                var url = getEmbedURL(project, version, doc, docpath, section, 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)
@@ -184,8 +191,9 @@ $(document).ready(function() {
         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);
+        var url = getEmbedURL(project, version, doc, docpath, section, url);
         $.get(url, function(data) {
             var content = $('<div></div>');
             content.html(data['content'][0]);

hoverxref/extension.py

@@ -3,6 +3,8 @@
 import types
 from docutils import nodes
 import sphinx
+from sphinx.ext.intersphinx import InventoryAdapter
+from sphinx.ext.intersphinx import missing_reference as sphinx_missing_reference
 from sphinx.roles import XRefRole
 from sphinx.util.fileutil import copy_asset
 from sphinx.util import logging
@@ -139,6 +141,114 @@ def setup_sphinx_tabs(app, config):
             app.disconnect(listener_id)
 
 
+def setup_intersphinx(app, config):
+    """
+    Disconnect ``missing-reference`` from ``sphinx.ext.intershinx``.
+
+    As there is no way to hook into the ``missing_referece`` function to add
+    some extra data to the docutils node returned by this function, we
+    disconnect the original listener and add our custom one.
+
+    https://github.com/sphinx-doc/sphinx/blob/53c1dff/sphinx/ext/intersphinx.py
+    """
+    if not app.config.hoverxref_intersphinx:
+        # Do not disconnect original intersphinx missing-reference if the user
+        # does not have hoverxref intersphinx enabled
+        return
+
+    if sphinx.version_info < (3, 0, 0):
+        listeners = list(app.events.listeners.get('missing-reference').items())
+    else:
+        listeners = [
+            (listener.id, listener.handler)
+            for listener in app.events.listeners.get('missing-reference')
+        ]
+    for listener_id, function in listeners:
+        module_name = inspect.getmodule(function).__name__
+        if module_name == 'sphinx.ext.intersphinx':
+            app.disconnect(listener_id)
+
+
+def missing_reference(app, env, node, contnode):
+    """
+    Override original ``missing_referece`` to add data into the node.
+
+    We call the original intersphinx extension and add hoverxref CSS classes
+    plus the ``data-url`` to the node returned from it.
+
+    Sphinx intersphinx downloads all the ``objects.inv`` and load each of them
+    into a "named inventory" and also updates the "main inventory". We check if
+    reference is part of any of the "named invetories" the user defined in
+    ``hoverxref_intersphinx`` and we add hoverxref to the node **only if** the
+    reference is on those inventories.
+
+    See https://github.com/sphinx-doc/sphinx/blob/4d90277c/sphinx/ext/intersphinx.py#L244-L250
+    """
+    if not app.config.hoverxref_intersphinx:
+        # Do nothing if the user doesn't have hoverxref intersphinx enabled
+        return
+
+    # We need to grab all the attributes before calling
+    # ``sphinx_missing_reference`` because it modifies the node in-place
+    domain = node.get('refdomain')  # ``std`` if used on ``:ref:``
+    target = node['reftarget']
+    reftype = node['reftype']
+
+    # By default we skip adding hoverxref to the node to avoid possible
+    # problems. We want to be sure we have to add hoverxref on it
+    skip_node = True
+    inventory_name_matched = None
+
+    if domain == 'std':
+        # Using ``:ref:`` manually, we could write intersphinx like:
+        # :ref:`datetime <python:datetime.datetime>`
+        # and the node will have these attribues:
+        #   refdomain: std
+        #   reftype: ref
+        #   reftarget: python:datetime.datetime
+        #   refexplicit: True
+        if ':' in target:
+            inventory_name, _ = target.split(':', 1)
+            if inventory_name in app.config.hoverxref_intersphinx:
+                skip_node = False
+                inventory_name_matched = inventory_name
+    else:
+        # Using intersphinx via ``sphinx.ext.autodoc`` generates links for docstrings like:
+        # :py:class:`float`
+        # and the node will have these attribues:
+        #   refdomain: py
+        #   reftype: class
+        #   reftarget: float
+        #   refexplicit: False
+        inventories = InventoryAdapter(env)
+
+        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:
+                # The object **does** exist on the inventories defined by the
+                # user: enable hoverxref on this node
+                skip_node = False
+                inventory_name_matched = inventory_name
+                break
+
+    newnode = sphinx_missing_reference(app, env, node, contnode)
+    if newnode is not None and not skip_node:
+        hoverxref_type = app.config.hoverxref_intersphinx_types.get(inventory_name_matched)
+        if isinstance(hoverxref_type, dict):
+            # Specific style for a particular reftype
+            hoverxref_type = hoverxref_type.get(reftype)
+        hoverxref_type = hoverxref_type or app.config.hoverxref_default_type
+
+        classes = newnode.get('classes')
+        classes.extend(['hoverxref', hoverxref_type])
+        newnode.replace_attr('classes', classes)
+        newnode._hoverxref = {
+            'data-url': newnode.get('refuri'),
+        }
+
+    return newnode
+
+
 def setup_translators(app):
     """
     Override translators respecting the one defined (if any).
@@ -255,6 +365,8 @@ def setup(app):
     app.add_config_value('hoverxref_ignore_refs', ['genindex', 'modindex', 'search'], 'env')
     app.add_config_value('hoverxref_role_types', {}, 'env')
     app.add_config_value('hoverxref_default_type', 'tooltip', 'env')
+    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')
 
     # Tooltipster settings
@@ -288,10 +400,13 @@ def setup(app):
 
     app.connect('config-inited', setup_domains)
     app.connect('config-inited', setup_sphinx_tabs)
+    app.connect('config-inited', setup_intersphinx)
     app.connect('config-inited', is_hoverxref_configured)
     app.connect('config-inited', setup_theme)
     app.connect('build-finished', copy_asset_files)
 
+    app.connect('missing-reference', missing_reference)
+
     for f in ASSETS_FILES:
         if f.endswith('.js') or f.endswith('.js_t'):
             app.add_js_file(f.replace('.js_t', '.js'))

tests/conftest.py

@@ -2,13 +2,13 @@
 import shutil
 import pytest
 
-from .utils import srcdir, prefixdocumentsrcdir, customobjectsrcdir, pythondomainsrcdir
+from .utils import srcdir, prefixdocumentsrcdir, customobjectsrcdir, pythondomainsrcdir, intersphinxsrc
 
 
 @pytest.fixture(autouse=True, scope='function')
 def remove_sphinx_build_output():
     """Remove _build/ folder, if exist."""
-    for path in (srcdir, prefixdocumentsrcdir, customobjectsrcdir, pythondomainsrcdir):
+    for path in (srcdir, prefixdocumentsrcdir, customobjectsrcdir, pythondomainsrcdir, intersphinxsrc):
         build_path = os.path.join(path, '_build')
         if os.path.exists(build_path):
             shutil.rmtree(build_path)

tests/examples/intersphinx/conf.py

@@ -0,0 +1,18 @@
+# conf.py to run tests
+
+master_doc = 'index'
+extensions = [
+    'hoverxref.extension',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc',
+]
+
+hoverxref_project = 'myproject'
+hoverxref_version = 'myversion'
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'readthedocs': ('https://docs.readthedocs.io/en/stable/', None),
+}
+intersphinx_cache_limit = 0