Merge branch 'master' of github.com:humitos/sphinx-hoverxref into humitos/micromodal

Author: humitos

.travis.yml

@@ -3,6 +3,7 @@ dist: xenial
 python:
   - 3.6
   - 3.7
+  - 3.8
 install:
   pip install tox-travis
 script:

MANIFEST.in

@@ -1,10 +1,16 @@
 prune common
 include LICENSE
+
 include hoverxref/_static/js/hoverxref.js_t
+
 include hoverxref/_static/js/tooltipster.bundle.min.js
 include hoverxref/_static/css/tooltipster.bundle.min.css
 include hoverxref/_static/css/tooltipster-sideTip-shadow.min.css
 include hoverxref/_static/css/tooltipster.custom.css
+include hoverxref/_static/css/tooltipster-sideTip-light.min.css
+include hoverxref/_static/css/tooltipster-sideTip-borderless.min.css
+include hoverxref/_static/css/tooltipster-sideTip-noir.min.css
+include hoverxref/_static/css/tooltipster-sideTip-punk.min.css
 
 include hoverxref/_static/js/micromodal.min.js
 include hoverxref/_static/css/micromodal.css

docs/conf.py

@@ -130,7 +130,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/requirements.txt

@@ -1,5 +1,5 @@
 sphinx==1.8.5  # pyup: ignore
-sphinx-autoapi==1.2.1
+sphinx-autoapi==1.3.0
 sphinx-rtd-theme==0.4.3
 sphinx-tabs==1.1.13
 sphinx-prompt==1.1.0

docs/usage.rst

@@ -71,11 +71,11 @@ An example using Python Domain would be like:
 
 .. code-block:: rst
 
-   :py:class:`hoverxref.domains.HoverXRefStandardDomain`
+   :py:class:`hoverxref.domains.HoverXRefStandardDomainMixin`
 
 That will render to:
 
-:py:class:`hoverxref.domains.HoverXRefStandardDomain`
+:py:class:`hoverxref.domains.HoverXRefStandardDomainMixin`
 
 
 To enable ``hoverxref`` on a domain, you need to use the config :confval:`hoverxref_domains`

hoverxref/_static/js/hoverxref.js_t

@@ -72,14 +72,15 @@ $(document).ready(function() {
             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');
 
-            console.debug('Data: project=' + project + ' version=' + version + ' doc=' + doc + ' section=' + section);
+            console.debug('Data: project=' + project + ' version=' + version + ' doc=' + doc + ' path=' + docpath + ' section=' + section);
 
             // we set a variable so the data is only loaded once via Ajax, not every time the tooltip opens
             if ($origin.data('loaded') !== true) {
                 // TODO: improve URL handling here
-                var url = '{{ hoverxref_api_host }}' + '/api/v2/embed/?' + 'project=' + project + '&version=' + version + '&doc=' + doc + '&section=' + section;
+                var url = '{{ hoverxref_api_host }}' + '/api/v2/embed/?' + 'project=' + project + '&version=' + version + '&doc=' + doc + '&path=' + docpath + '&section=' + section;
                 $.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)

hoverxref/domains.py

@@ -1,5 +1,3 @@
-from sphinx.domains.python import PythonDomain
-from sphinx.domains.std import StandardDomain
 from sphinx.util import logging
 from .utils import get_ref_xref_data, get_ref_obj_data
 
@@ -13,7 +11,7 @@ def _is_hoverxref_configured(self, env):
         version = env.config.hoverxref_version
         return project and version
 
-    def _inject_hoverxref_data(self, env, refnode, docname, labelid):
+    def _inject_hoverxref_data(self, env, refnode, docname, docpath, labelid):
         refnode.replace_attr('classes', ['hoverxref'])
 
         project = env.config.hoverxref_project
@@ -22,11 +20,17 @@ def _inject_hoverxref_data(self, env, refnode, docname, labelid):
             'data-project': project,
             'data-version': version,
             'data-doc': docname,
+            'data-docpath': docpath,
             'data-section': labelid,
         }
 
+    def _get_docpath(self, builder, docname):
+        docpath = builder.get_outfilename(docname)
+        docpath = docpath.replace(builder.outdir, '')
+        return docpath
 
-class HoverXRefPythonDomain(HoverXRefBaseDomain, PythonDomain):
+
+class HoverXRefPythonDomainMixin(HoverXRefBaseDomain):
 
     def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode):
         refnode = super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
@@ -42,7 +46,9 @@ def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode):
 
         if self._is_hoverxref_configured(env):
             docname, labelid = obj[0], name
-            self._inject_hoverxref_data(env, refnode, docname, labelid)
+            docpath = self._get_docpath(builder, docname)
+
+            self._inject_hoverxref_data(env, refnode, docname, docpath, labelid)
             logger.info(
                 ':ref: _hoverxref injected: fromdocname=%s %s',
                 fromdocname,
@@ -51,9 +57,9 @@ def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode):
         return refnode
 
 
-class HoverXRefStandardDomain(HoverXRefBaseDomain, StandardDomain):
+class HoverXRefStandardDomainMixin(HoverXRefBaseDomain):
     """
-    Override ``StandardDomain`` to save the values after the xref resolution.
+    Mixin for ``StandardDomain`` to save the values after the xref resolution.
 
     ``:ref:`` are treating as a different node in Sphinx
     (``sphinx.addnodes.pending_xref``). These nodes are translated to regular
@@ -83,7 +89,9 @@ def _resolve_ref_xref(self, env, fromdocname, builder, typ, target, node, contno
 
         if self._is_hoverxref_configured(env) and (env.config.hoverxref_auto_ref or typ == 'hoverxref'):
             docname, labelid, _ = get_ref_xref_data(self, node, target)
-            self._inject_hoverxref_data(env, refnode, docname, labelid)
+            docpath = self._get_docpath(builder, docname)
+
+            self._inject_hoverxref_data(env, refnode, docname, docpath, labelid)
             logger.info(
                 ':ref: _hoverxref injected: fromdocname=%s %s',
                 fromdocname,
@@ -99,7 +107,9 @@ def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contno
         if typ in env.config.hoverxref_roles:
             docname, labelid = get_ref_obj_data(self, node, typ, target)
             if self._is_hoverxref_configured(env):
-                self._inject_hoverxref_data(env, refnode, docname, labelid)
+                docpath = self._get_docpath(builder, docname)
+
+                self._inject_hoverxref_data(env, refnode, docname, docpath, labelid)
                 logger.info(
                     ':%s: _hoverxref injected: fromdocname=%s %s',
                     typ,

hoverxref/extension.py

@@ -1,13 +1,15 @@
 import os
 import inspect
+import types
 from docutils import nodes
+import sphinx
 from sphinx.roles import XRefRole
 from sphinx.util.fileutil import copy_asset
 from sphinx.util import logging
 
 from . import version
-from .domains import HoverXRefPythonDomain, HoverXRefStandardDomain
-from .translators import HoverXRefHTMLTranslator
+from .domains import HoverXRefPythonDomainMixin, HoverXRefStandardDomainMixin
+from .translators import HoverXRefHTMLTranslatorMixin
 
 logger = logging.getLogger(__name__)
 
@@ -72,6 +74,13 @@ def copy_asset_files(app, exception):
 
 
 def setup_domains(app, config):
+    """
+    Override domains respecting the one defined (if any).
+
+    We create a new class by inheriting the Sphinx Domain already defined
+    and our own ``HoverXRef...DomainMixin`` that includes the logic for
+    ``_hoverxref`` attributes.
+    """
     # Add ``hoverxref`` role replicating the behavior of ``ref``
     app.add_role_to_domain(
         'std',
@@ -82,10 +91,27 @@ def setup_domains(app, config):
             warn_dangling=True,
         ),
     )
-    app.add_domain(HoverXRefStandardDomain, override=True)
 
-    if 'py' in config.hoverxref_domains:
-        app.add_domain(HoverXRefPythonDomain, override=True)
+    domain = types.new_class(
+        'HoverXRefStandardDomain',
+        (
+            HoverXRefStandardDomainMixin,
+            app.registry.domains.get('std'),
+        ),
+        {}
+    )
+    app.add_domain(domain, override=True)
+
+    if 'py' in app.config.hoverxref_domains:
+        domain = types.new_class(
+            'HoverXRefPythonDomain',
+            (
+                HoverXRefPythonDomainMixin,
+                app.registry.domains.get('py'),
+            ),
+            {}
+        )
+        app.add_domain(domain, override=True)
 
 
 def setup_sphinx_tabs(app, config):
@@ -95,13 +121,54 @@ def setup_sphinx_tabs(app, config):
     Sphinx Tabs removes the CSS/JS from pages that does not use the directive.
     Although, we need them to use inside the tooltip.
     """
-    listeners = list(app.events.listeners.get('html-page-context').items())
+    if sphinx.version_info < (3, 0, 0):
+        listeners = list(app.events.listeners.get('html-page-context').items())
+    else:
+        listeners = [
+            (listener.id, listener.handler)
+            for listener in app.events.listeners.get('html-page-context')
+        ]
     for listener_id, function in listeners:
         module_name = inspect.getmodule(function).__name__
         if module_name == 'sphinx_tabs.tabs':
             app.disconnect(listener_id)
 
 
+def setup_translators(app):
+    """
+    Override translators respecting the one defined (if any).
+
+    We create a new class by inheriting the Sphinx Translator already defined
+    and our own ``HoverXRefHTMLTranslatorMixin`` that includes the logic to
+    ``_hoverxref`` attributes.
+    """
+    if not app.registry.translators.items():
+        translator = types.new_class(
+            'HoverXRefHTMLTranslator',
+            (
+                HoverXRefHTMLTranslatorMixin,
+                app.builder.default_translator_class,
+            ),
+            {},
+        )
+        app.set_translator(app.builder.name, translator, override=True)
+    else:
+        for name, klass in app.registry.translators.items():
+            if app.builder.format != 'html':
+                # Skip translators that are not HTML
+                continue
+
+            translator = types.new_class(
+                'HoverXRefHTMLTranslator',
+                (
+                    HoverXRefHTMLTranslatorMixin,
+                    klass,
+                ),
+                {},
+            )
+            app.set_translator(name, translator, override=True)
+
+
 def setup_theme(app, exception):
     """
     Auto-configure default settings for known themes.
@@ -145,6 +212,7 @@ def deprecated_configs_warning(app, exception):
         app.config.hoverxref_api_host = app.config.hoverxref_tooltip_api_host
 
 
+
 def setup(app):
     """Setup ``hoverxref`` Sphinx extension."""
 
@@ -188,12 +256,7 @@ def setup(app):
     app.add_config_value('hoverxref_modal_default_title', 'Note', 'env')
     app.add_config_value('hoverxref_modal_prefix_title', '📝 ', 'env')
 
-    app.set_translator('html', HoverXRefHTMLTranslator, override=True)
-
-    # Read the Docs use ``readthedocs`` as the name of the build, so we need to
-    # replace this as well
-    app.set_translator('readthedocs', HoverXRefHTMLTranslator, override=True)
-    app.set_translator('readthedocsdirhtml', HoverXRefHTMLTranslator, override=True)
+    app.connect('builder-inited', setup_translators)
 
     app.connect('config-inited', deprecated_configs_warning)
 

hoverxref/translators.py

@@ -1,13 +1,12 @@
-from sphinx.writers.html import HTMLTranslator
 from sphinx.util import logging
 
 logger = logging.getLogger(__name__)
 
 
-class HoverXRefHTMLTranslator(HTMLTranslator):
+class HoverXRefHTMLTranslatorMixin:
 
     """
-    Override ``HTMLTranslator`` to render extra data saved in reference nodes.
+    Mixin ``HTMLTranslator`` to render extra data saved in reference nodes.
 
     It adds all the values saved under ``_hoverxref`` as attributes of the HTML
     reference tag.

tests/examples/python-domain/api.rst

@@ -3,7 +3,7 @@
 API
 ===
 
-.. autoclass:: hoverxref.extension.HoverXRefStandardDomain
+.. autoclass:: hoverxref.extension.HoverXRefStandardDomainMixin
 
 
 .. automodule:: hoverxref.extension