Support :doc: role

Inject hoverxref data in :doc: roles.

It adds a new config (`hoverxref_auto_doc`) that works in a similar way as
`hoverxref_auto_ref` by enabling hoverxref in all `:doc:` roles.

Author: humitos

hoverxref/domains.py

@@ -1,5 +1,5 @@
 from sphinx.util import logging
-from .utils import get_ref_xref_data, get_ref_obj_data
+from .utils import get_ref_xref_data, get_ref_obj_data, get_ref_doc_data
 
 logger = logging.getLogger(__name__)
 
@@ -145,6 +145,29 @@ def _resolve_ref_xref(self, env, fromdocname, builder, typ, target, node, contno
         )
         return refnode
 
+    def _resolve_doc_xref(self, env, fromdocname, builder, typ, target, node, contnode):
+        refnode = super()._resolve_doc_xref(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),
+                not env.config.hoverxref_auto_doc,
+        ]):
+            return refnode
+
+        docname = get_ref_doc_data(env, node, fromdocname)
+        docpath = self._get_docpath(builder, docname)
+        self._inject_hoverxref_data(env, refnode, typ, docname, docpath, '')
+        logger.debug(
+            ':%s: _hoverxref injected: fromdocname=%s %s',
+            typ,
+            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:

hoverxref/extension.py

@@ -248,6 +248,7 @@ def setup(app):
     app.add_config_value('hoverxref_project', default_project, 'html')
     app.add_config_value('hoverxref_version', default_version, 'html')
     app.add_config_value('hoverxref_auto_ref', False, 'env')
+    app.add_config_value('hoverxref_auto_doc', False, 'env')
     app.add_config_value('hoverxref_mathjax', False, 'env')
     app.add_config_value('hoverxref_sphinxtabs', False, 'env')
     app.add_config_value('hoverxref_roles', [], 'env')

hoverxref/translators.py

@@ -15,6 +15,7 @@ class HoverXRefHTMLTranslatorMixin:
     def starttag(self, node, tagname, suffix='\n', empty=False, **attributes):
         if tagname == 'a' and hasattr(node, '_hoverxref'):
             attributes.update(node._hoverxref)
-            logger.info('_hoverxref attributes: %s', attributes)
+            logger.debug('node.astext: %s', node.astext())
+            logger.debug('_hoverxref attributes: %s', attributes)
 
         return super().starttag(node, tagname, suffix, empty, **attributes)

hoverxref/utils.py

@@ -1,4 +1,5 @@
 import sphinx
+from sphinx.util import docname_join
 
 
 def get_ref_xref_data(domain, node, target):
@@ -52,3 +53,18 @@ def get_ref_obj_data(domain, node, typ, target):
                 docname, labelid = domain.objects[objtype, target]
                 break
     return docname, labelid
+
+
+def get_ref_doc_data(env, node, fromdocname):
+    """
+    Use Sphinx's internals to get the docname from a reftarget.
+
+    :returns: docname
+    :rtype: str
+    """
+    # Borrowed from https://github.com/sphinx-doc/sphinx/blob/6ef08a42df4534dbb2664d49dc10a16f6df2acb2/sphinx/domains/std.py#L791-L749
+    refdoc = node.get('refdoc', fromdocname)
+    docname = docname_join(refdoc, node['reftarget'])
+    if docname not in env.all_docs:
+        return None
+    return docname

tests/examples/default/index.rst

@@ -16,3 +16,8 @@ Example Reference
 -----------------
 
 This is a reference to :ref:`example-reference`.
+
+doc role example
+----------------
+
+:doc:`This is a :doc: to another document <chapter-i>`.

tests/test_htmltag.py

@@ -38,6 +38,29 @@ def test_project_version_settings(app, status, warning):
     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="hoverxref tooltip reference internal" data-doc="chapter-i" data-docpath="/chapter-i.html" 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>',
+        '<a class="reference internal" href="chapter-i.html"><span class="doc">This is a :doc: to another document</span></a>',
+    ]
+
+    for chunk in chunks:
+        assert chunk in content
+
+
+@pytest.mark.sphinx(
+    srcdir=srcdir,
+    confoverrides={
+        'hoverxref_project': 'myproject',
+        'hoverxref_version': 'myversion',
+        'hoverxref_auto_doc': True,
+    },
+)
+def test_doc_role(app, status, warning):
+    app.build()
+    path = app.outdir / 'index.html'
+    assert path.exists() is True
+    content = open(path).read()
+
+    chunks = [
+        '<a class="hoverxref tooltip reference internal" data-doc="chapter-i" data-docpath="/chapter-i.html" data-project="myproject" data-section="" data-version="myversion" href="chapter-i.html"><span class="doc">This is a :doc: to another document</span></a>',
     ]
 
     for chunk in chunks: