Merge pull request readthedocs#71 from readthedocs/humitos/support-numref

Author: humitos

docs/configuration.rst

@@ -20,6 +20,8 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
    Default: ``{}``
 
+   Type: dictionary
+
    Example:
 
    .. code-block:: python
@@ -32,7 +34,6 @@ These settings are global and have effect on both, tooltips and modal dialogues.
           'class': 'tooltip',  # for Python Sphinx Domain
       }
 
-   Type: dictionary
 
 .. confval:: hoverxref_default_type
 
@@ -80,6 +81,17 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
    Type: list
 
+   Example:
+
+   .. code-block:: python
+
+      hoverxref_roles = [
+          'numref',
+          'confval',
+          'setting',
+      ]
+
+
 .. confval:: hoverxref_sphinxtabs
 
    Description: trigger an extra step to render tooltips where its content has a `Sphinx Tabs`_

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_numref_data
 
 logger = logging.getLogger(__name__)
 
@@ -167,3 +167,27 @@ def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contno
             refnode._hoverxref,
         )
         return refnode
+
+    # TODO: combine this method with ``_resolve_obj_xref``
+    def _resolve_numref_xref(self, env, fromdocname, builder, typ, target, node, contnode):
+        refnode = super()._resolve_numref_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),
+                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,
+        )
+        return refnode

hoverxref/utils.py

@@ -52,3 +52,25 @@ def get_ref_obj_data(domain, node, typ, target):
                 docname, labelid = domain.objects[objtype, target]
                 break
     return docname, labelid
+
+
+def get_ref_numref_data(domain, node, typ, target):
+    """
+    Use Sphinx's internals to resolve :numref: and returns this data.
+
+    :returns: tuple (``docname``, ``labelid``)
+    """
+    # Borrowed from https://github.com/sphinx-doc/sphinx/blob/47cd262b3e50ed650a82f272ba128a1f872cda4d/sphinx/domains/std.py#L699-L702
+    if sphinx.version_info < (2, 1):
+        if node['refexplicit']:
+            docname, labelid = domain.data['anonlabels'].get(target, ('', ''))
+        else:
+            # reference to named label; the final node will
+            # contain the section name after the label
+            docname, labelid, sectname = domain.data['labels'].get(target, ('', '', ''))
+    else:
+        if target in domain.labels:
+            docname, labelid, figname = domain.labels.get(target, ('', '', ''))
+        else:
+            docname, labelid = domain.anonlabels.get(target, ('', ''))
+    return docname, labelid

tests/examples/custom-object/code.rst

@@ -0,0 +1,15 @@
+:orphan:
+
+Code
+====
+
+
+This is a page with some code blocks directives
+
+
+.. code-block:: python
+   :caption: PyExample
+   :name: python-code-block
+
+   import datetime
+   datetime.datetime.now()

tests/examples/custom-object/conf.py

@@ -10,8 +10,10 @@
 hoverxref_version = 'myversion'
 hoverxref_roles = [
     'confval',
+    'numref',
 ]
 
+numfig = True
 
 def setup(app):
     app.add_object_type(

tests/examples/custom-object/index.rst

@@ -8,3 +8,12 @@ This documentation contains user-defined objects using ``Sphinx.add_object_type`
 :confval:`This is a :confval: to conf-title <conf-title>`.
 
 :hoverxref:`This is a :hoverxref: to Configuration document <configuration>`.
+
+:numref:`This is a :numref: to a Python code block ({name}) <python-code-block>`.
+
+
+.. code page needs to be in the toctree for numfig=True to work and number it correctly
+
+.. toctree::
+
+   code

tests/test_htmltag.py

@@ -108,6 +108,7 @@ def test_custom_object(app, status, warning):
     chunks = [
         '<a class="hoverxref tooltip reference internal" data-doc="configuration" data-docpath="/configuration.html" data-project="myproject" data-section="confval-conf-title" data-version="myversion" href="configuration.html#confval-conf-title"><code class="xref std std-confval docutils literal notranslate"><span class="pre">This</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">:confval:</span> <span class="pre">to</span> <span class="pre">conf-title</span></code></a>',
         '<a class="hoverxref tooltip reference internal" data-doc="configuration" data-docpath="/configuration.html" data-project="myproject" data-section="configuration" data-version="myversion" href="configuration.html#configuration"><span class="std std-ref">This is a :hoverxref: to Configuration document</span></a>',
+        '<a class="hoverxref tooltip reference internal" data-doc="code" data-docpath="/code.html" data-project="myproject" data-section="python-code-block" data-version="myversion" href="code.html#python-code-block"><span class="std std-numref">This is a :numref: to a Python code block (PyExample)</span></a>'
     ]
 
     for chunk in chunks: