Merge pull request readthedocs#49 from readthedocs/humitos/ignore-refs

Add `hoverxref_ignore_refs` to ignore user-defined references

Author: humitos

docs/configuration.rst

@@ -16,8 +16,7 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
 .. confval:: hoverxref_default_types
 
-   Description: Style to use by default when for the embedded content when using ``:hoverxref:`` role.
-   It also affect the style of and ``:ref:``
+   Description: Style to use by default when hover each type of reference (role).
 
    Default: ``{}``
 
@@ -53,6 +52,14 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
    Type: bool
 
+.. confval:: hoverxref_ignore_refs
+
+   Description: Ignore to add tooltip on specific references. Useful when using :confval:`hoverxref_auto_ref`
+
+   Default: ``['genindex', 'modindex', 'search']``
+
+   Type: list
+
 .. confval:: hoverxref_domains
 
    Description: List containing the Sphinx Domain's names where ``hoverxref`` has to be applied.

hoverxref/domains.py

@@ -12,11 +12,6 @@ class HoverXRefBaseDomain:
         'hoverxrefmodal',
     )
 
-    def _is_hoverxref_configured(self, env):
-        project = env.config.hoverxref_project
-        version = env.config.hoverxref_version
-        return project and version
-
     def _inject_hoverxref_data(self, env, refnode, typ, docname, docpath, labelid):
         classes = ['hoverxref']
         type_class = None
@@ -56,13 +51,28 @@ def _get_docpath(self, builder, docname):
         docpath = docpath.replace(builder.outdir, '')
         return docpath
 
+    def _is_ignored_ref(self, env, target):
+        if target in env.config.hoverxref_ignore_refs:
+            logger.info(
+                'Ignoring reference in hoverxref_ignore_refs. target=%s',
+                target,
+            )
+            return True
+        return False
+
 
 class HoverXRefPythonDomainMixin(HoverXRefBaseDomain):
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         refnode = super().resolve_xref(env, fromdocname, builder, typ, target, node, contnode)
         if refnode is None:
-            return
+            return refnode
+
+        if any([
+                not env.config.hoverxref_is_configured,
+                self._is_ignored_ref(env, target),
+        ]):
+            return refnode
 
         modname = node.get('py:module')
         clsname = node.get('py:class')
@@ -71,16 +81,14 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
                                 typ, searchmode)
         name, obj = matches[0]
 
-        if self._is_hoverxref_configured(env):
-            docname, labelid = obj[0], name
-            docpath = self._get_docpath(builder, docname)
-
-            self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
-            logger.info(
-                ':ref: _hoverxref injected: fromdocname=%s %s',
-                fromdocname,
-                refnode._hoverxref,
-            )
+        docname, labelid = obj[0], name
+        docpath = self._get_docpath(builder, docname)
+        self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
+        logger.info(
+            ':ref: _hoverxref injected: fromdocname=%s %s',
+            fromdocname,
+            refnode._hoverxref,
+        )
         return refnode
 
 
@@ -107,40 +115,45 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
     def _resolve_ref_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         refnode = super()._resolve_ref_xref(env, fromdocname, builder, typ, target, node, contnode)
         if refnode is None:
-            return
-
-        if not self._is_hoverxref_configured(env) and typ in self.hoverxref_types:
-            # Using ``:hoverxref:`` role without having hoverxref configured
-            # properly. Log a warning.
-            logger.warning('hoverxref role is not fully configured.')
-
-        if self._is_hoverxref_configured(env) and (env.config.hoverxref_auto_ref or typ in self.hoverxref_types):
-            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.info(
-                ':ref: _hoverxref injected: fromdocname=%s %s',
-                fromdocname,
-                refnode._hoverxref,
-            )
+            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.info(
+            ':ref: _hoverxref injected: fromdocname=%s %s',
+            fromdocname,
+            refnode._hoverxref,
+        )
         return refnode
 
     def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contnode):
         refnode = super()._resolve_obj_xref(env, fromdocname, builder, typ, target, node, contnode)
         if refnode is None:
-            return
-
-        if typ in env.config.hoverxref_roles:
-            docname, labelid = get_ref_obj_data(self, node, typ, target)
-            if self._is_hoverxref_configured(env):
-                docpath = self._get_docpath(builder, docname)
-
-                self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
-                logger.info(
-                    ':%s: _hoverxref injected: fromdocname=%s %s',
-                    typ,
-                    fromdocname,
-                    refnode._hoverxref,
-                )
+            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.info(
+            ':%s: _hoverxref injected: fromdocname=%s %s',
+            typ,
+            fromdocname,
+            refnode._hoverxref,
+        )
         return refnode

hoverxref/extension.py

@@ -174,6 +174,26 @@ def setup_translators(app):
             app.set_translator(name, translator, override=True)
 
 
+def is_hoverxref_configured(app, config):
+    """
+    Save a config if hoverxref is properly configured.
+
+    It checks for ``hoverxref_project`` and ``hoverxref_version`` being defined
+    and set ``hoverxref_is_configured=True`` if configured.
+    """
+    config.hoverxref_is_configured = True
+
+    project = config.hoverxref_project
+    version = config.hoverxref_version
+    if not project or not version:
+        config.hoverxref_is_configured = False
+        # ``hoverxref`` extension is not fully configured
+        logger.warning(
+            'hoverxref extension is not fully configured. '
+            'Set hoverxref_project and hoverxref_version in your conf.py file.',
+        )
+
+
 def setup_theme(app, exception):
     """
     Auto-configure default settings for known themes.
@@ -230,10 +250,9 @@ def setup(app):
     app.add_config_value('hoverxref_sphinxtabs', False, 'env')
     app.add_config_value('hoverxref_roles', [], 'env')
     app.add_config_value('hoverxref_domains', [], 'env')
-
+    app.add_config_value('hoverxref_ignore_refs', ['genindex', 'modindex', 'search'], 'env')
     app.add_config_value('hoverxref_default_types', {}, 'env')
     app.add_config_value('hoverxref_default_type', 'tooltip', 'env')
-
     app.add_config_value('hoverxref_api_host', 'https://readthedocs.org', 'env')
 
     # Tooltipster settings
@@ -267,6 +286,7 @@ def setup(app):
 
     app.connect('config-inited', setup_domains)
     app.connect('config-inited', setup_sphinx_tabs)
+    app.connect('config-inited', is_hoverxref_configured)
     app.connect('config-inited', setup_theme)
     app.connect('build-finished', copy_asset_files)
 

tests/test_htmltag.py

@@ -192,3 +192,32 @@ def test_default_types(app, status, warning):
 
     for chunk in chunks:
         assert chunk in content
+
+
+@pytest.mark.sphinx(
+    srcdir=srcdir,
+    confoverrides={
+        'hoverxref_ignore_refs': [
+            'section i',
+        ],
+    },
+)
+def test_ignore_refs(app, status, warning):
+    app.build()
+    path = app.outdir / 'index.html'
+    assert path.exists() is True
+    content = open(path).read()
+
+    chunks = [
+        '<a class="reference internal" href="chapter-i.html#chapter-i"><span class="std std-ref">This a :ref: to Chapter I</span></a>',
+        '<a class="reference internal" href="chapter-i.html#section-i"><span class="std std-ref">This a :hoverxref: to Chapter I, Section I</span></a>',
+    ]
+
+    for chunk in chunks:
+        assert chunk in content
+
+    ignored_chunks = [
+        '<a class="hoverxref reference internal" data-doc="chapter-i" data-project="myproject" data-section="section-i" data-version="myversion" href="chapter-i.html#section-i"><span class="std std-ref">This a :hoverxref: to Chapter I, Section I</span></a>',
+    ]
+    for chunk in ignored_chunks:
+        assert chunk not in content