From d8831f66678d4648d22f7929a9e4699665b83476 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 20 Apr 2020 17:55:43 +0200 Subject: [PATCH 1/3] Support tooltips in :numref: --- hoverxref/domains.py | 26 +++++++++++++++++++++++++- hoverxref/utils.py | 22 ++++++++++++++++++++++ tests/examples/custom-object/code.rst | 15 +++++++++++++++ tests/examples/custom-object/conf.py | 2 ++ tests/examples/custom-object/index.rst | 9 +++++++++ tests/test_htmltag.py | 1 + 6 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 tests/examples/custom-object/code.rst diff --git a/hoverxref/domains.py b/hoverxref/domains.py index 8e256fb6..6baf721a 100644 --- a/hoverxref/domains.py +++ b/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 diff --git a/hoverxref/utils.py b/hoverxref/utils.py index 4559bc48..06d83f40 100644 --- a/hoverxref/utils.py +++ b/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 diff --git a/tests/examples/custom-object/code.rst b/tests/examples/custom-object/code.rst new file mode 100644 index 00000000..86e1f17c --- /dev/null +++ b/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() diff --git a/tests/examples/custom-object/conf.py b/tests/examples/custom-object/conf.py index 15401fa0..11241721 100644 --- a/tests/examples/custom-object/conf.py +++ b/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( diff --git a/tests/examples/custom-object/index.rst b/tests/examples/custom-object/index.rst index 602bc9ee..2df71d31 100644 --- a/tests/examples/custom-object/index.rst +++ b/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 `. :hoverxref:`This is a :hoverxref: to Configuration document `. + +:numref:`This is a :numref: to a Python code block ({name}) `. + + +.. code page needs to be in the toctree for numfig=True to work and number it correctly + +.. toctree:: + + code diff --git a/tests/test_htmltag.py b/tests/test_htmltag.py index 6077d369..8ff8d016 100644 --- a/tests/test_htmltag.py +++ b/tests/test_htmltag.py @@ -106,6 +106,7 @@ def test_custom_object(app, status, warning): chunks = [ 'This is a :confval: to conf-title', 'This is a :hoverxref: to Configuration document', + 'This is a :numref: to a Python code block (PyExample)' ] for chunk in chunks: From 17d32a39f1a3221885fe32e725c897e0be0c768d Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 24 Apr 2020 16:37:57 +0200 Subject: [PATCH 2/3] Add an example for `hoverxref_roles` in the configuration page --- docs/configuration.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/configuration.rst b/docs/configuration.rst index 781bc638..c725d92a 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -80,6 +80,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`_ From 3fb36cd9fda7d3e95c3f3ebe1de0aff915af7639 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 24 Apr 2020 16:41:35 +0200 Subject: [PATCH 3/3] Move the type upper in the docs --- docs/configuration.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index c725d92a..36d0e77b 100644 --- a/docs/configuration.rst +++ b/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