Add support for both styles in the same documentation

humitos · humitos · commit 7bf95524dcc5 · 2020-04-09T01:04:51.000+02:00
diff --git a/docs/_images/modal-example.png b/docs/_images/modal-example.png
diff --git a/docs/_images/tooltip-example.png b/docs/_images/tooltip-example.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -71,8 +71,6 @@
 hoverxref_sphinxtabs = True
 hoverxref_mathjax = True
 
-hoverxref_type = 'modal'
-
 versionwarning_messages = {
     'latest': 'This extension is currently in Beta state. '
     'This means that there may be some things not well supported or unexpected behavior. '
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,49 +1,63 @@
 Welcome to sphinx-hoverxref!
 ============================
 
-``sphinx-hoverxref`` is a Sphinx_ extension to show a floating window (tooltips or modal dialogues) on the cross references of the documentation embedding the content of the linked section on them. With ``sphinx-hoverxref``, you don't need to click a link to see what's in there.
+``sphinx-hoverxref`` is a Sphinx_ extension to show a floating window (*tooltips* or *modal* dialogues) on the cross references of the documentation embedding the content of the linked section on them. With ``sphinx-hoverxref``, you don't need to click a link to see what's in there.
 
-We currently support two different types of floating windows: Tooltip_ and Modal_.
 
+Usage
+-----
 
-Tooltip
--------
+To show a floating window, use the role ``hoverxref`` to link to any document or section and embed its content into it.
+We currently support two different types of floating windows: Tooltip and Modal.
 
-By defining :confval:`hoverxref_type <hoverxref_type>` as ``'tooltip'`` (default) you will get a tooltip when hover references.
 
-.. figure:: _images/tooltip-example.png
-   :width: 75%
-   :class: example
+.. tabs::
 
+   .. tab:: Default
 
-Modal
------
+      Writing this reStructuredText in your document:
 
-By defining :confval:`hoverxref_type <hoverxref_type>` as ``'modal'`` you will get a modal when hover references.
+      .. code-block:: rst
 
-.. image:: _images/modal-example.png
-   :width: 75%
-   :class: example
+         This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
 
+      it will be rendered to:
+
+      This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
+
+      .. note::
+
+         The default style (tooltip or modal) is defined by the config :confval:`hoverxref_type <hoverxref_type>`.
+
+
+   .. tab:: Tooltip style
+
+      To *force* the floating window to be a tooltip, you can use ``:hoverxreftooltip:`` role instead.
+
+      .. code-block:: rst
+
+         This will :hoverxreftooltip:`show a tooltip <hoverxref:hoverxref>` in the linked words.
+
+      it will be rendered to:
+
+      This will :hoverxreftooltip:`show a tooltip <hoverxref:hoverxref>` in the linked words.
 
-Usage
------
 
-To show a floating window on a reference, use the role ``hoverxref`` to link to any document or section.
+   .. tab:: Modal style
 
-Writing this reStructuredText in your document:
+      To *force* the floating window to be a modal, you can use ``:hoverxrefmodal:`` role instead.
 
-.. code-block:: rst
+      .. code-block:: rst
 
-   This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
+         This will :hoverxrefmodal:`show a modal <hoverxref:hoverxref>` in the linked words.
 
-it will be rendered to:
+      it will be rendered to:
 
-This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
+      This will :hoverxrefmodal:`show a modal <hoverxref:hoverxref>` in the linked words.
 
 .. tip::
 
-   This new ``hoverxref`` role is an alias of the ``ref`` role and works in the same.
+   These new roles are alias of the ``ref`` role and works in the same.
    See :ref:`usage:usage` for more detailed information about this and other examples.
 
 
diff --git a/hoverxref/_static/js/hoverxref.js_t b/hoverxref/_static/js/hoverxref.js_t
@@ -57,8 +57,7 @@ function reLoadSphinxTabs() {
 
 
 $(document).ready(function() {
-    {% if hoverxref_type == 'tooltip' %}
-    $('.hoverxref').tooltipster({
+    $('.hoverxref.tooltip').tooltipster({
         theme: {{ hoverxref_tooltip_theme }},
         interactive: {{ 'true' if hoverxref_tooltip_interactive else 'false' }},
         maxWidth: {{ hoverxref_tooltip_maxwidth }},
@@ -105,9 +104,7 @@ $(document).ready(function() {
             );
         }
     })
-    {% endif %}
 
-    {% if hoverxref_type == 'modal' %}
     var modalHtml = `
   <div class="modal micromodal-slide {{ hoverxref_modal_class }}" id="micromodal" aria-hidden="true">
     <div class="modal__overlay" tabindex="-1" data-micromodal-close>
@@ -149,9 +146,10 @@ $(document).ready(function() {
         var project = element.data('project');
         var version = element.data('version');
         var doc = element.data('doc');
+        var docpath = element.data('docpath');
         var section = element.data('section');
-        console.debug('Data: project=' + project + ' version=' + version + ' doc=' + doc + ' section=' + section);
-        var url = '{{ hoverxref_api_host }}' + '/api/v2/embed/?' + 'project=' + project + '&version=' + version + '&doc=' + doc + '&section=' + section;
+        console.debug('Data: project=' + project + ' version=' + version + ' doc=' + doc + ' path=' + docpath + ' section=' + section);
+        var url = '{{ hoverxref_api_host }}' + '/api/v2/embed/?' + 'project=' + project + '&version=' + version + '&doc=' + doc + '&path=' + docpath + '&section=' + section;
 
         $.get(url, function(data) {
             var content = $('<div></div>');
@@ -194,7 +192,7 @@ $(document).ready(function() {
     };
 
     var delay = {{ hoverxref_modal_hover_delay }}, setTimeoutConst;
-    $('.hoverxref').hover(function(event) {
+    $('.hoverxref.modal').hover(function(event) {
         var element = $(this);
         console.debug('Event: ' + event + ' Element: ' + element);
         event.preventDefault();
@@ -205,5 +203,4 @@ $(document).ready(function() {
     }, function(){
         clearTimeout(setTimeoutConst);
     });
-    {% endif %}
 });
diff --git a/hoverxref/domains.py b/hoverxref/domains.py
@@ -6,13 +6,20 @@
 
 class HoverXRefBaseDomain:
 
+    hoverxref_types = (
+        'hoverxref',
+        'hoverxreftooltip',
+        '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, docname, docpath, labelid):
-        refnode.replace_attr('classes', ['hoverxref'])
+    def _inject_hoverxref_data(self, env, refnode, typ, docname, docpath, labelid):
+        type_class = 'tooltip' if typ == 'hoverxreftooltip' else ('modal' if typ == 'hoverxrefmodal' else env.config.hoverxref_default_type)
+        refnode.replace_attr('classes', ['hoverxref', type_class])
 
         project = env.config.hoverxref_project
         version = env.config.hoverxref_version
@@ -32,23 +39,23 @@ def _get_docpath(self, builder, docname):
 
 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)
+    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
 
         modname = node.get('py:module')
         clsname = node.get('py:class')
         searchmode = node.hasattr('refspecific') and 1 or 0
         matches = self.find_obj(env, modname, clsname, target,
-                                type, searchmode)
+                                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, docname, docpath, labelid)
+            self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
             logger.info(
                 ':ref: _hoverxref injected: fromdocname=%s %s',
                 fromdocname,
@@ -70,7 +77,7 @@ class HoverXRefStandardDomainMixin(HoverXRefBaseDomain):
     """
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
-        if typ == 'hoverxref':
+        if typ in self.hoverxref_types:
             resolver = self._resolve_ref_xref
             return resolver(env, fromdocname, builder, typ, target, node, contnode)
 
@@ -82,16 +89,16 @@ def _resolve_ref_xref(self, env, fromdocname, builder, typ, target, node, contno
         if refnode is None:
             return
 
-        if not self._is_hoverxref_configured(env) and typ == 'hoverxref':
+        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 == 'hoverxref'):
+        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, docname, docpath, labelid)
+            self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
             logger.info(
                 ':ref: _hoverxref injected: fromdocname=%s %s',
                 fromdocname,
@@ -109,7 +116,7 @@ def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contno
             if self._is_hoverxref_configured(env):
                 docpath = self._get_docpath(builder, docname)
 
-                self._inject_hoverxref_data(env, refnode, docname, docpath, labelid)
+                self._inject_hoverxref_data(env, refnode, typ, docname, docpath, labelid)
                 logger.info(
                     ':%s: _hoverxref injected: fromdocname=%s %s',
                     typ,
diff --git a/hoverxref/extension.py b/hoverxref/extension.py
@@ -8,7 +8,11 @@
 from sphinx.util import logging
 
 from . import version
-from .domains import HoverXRefPythonDomainMixin, HoverXRefStandardDomainMixin
+from .domains import (
+    HoverXRefBaseDomain,
+    HoverXRefPythonDomainMixin,
+    HoverXRefStandardDomainMixin,
+)
 from .translators import HoverXRefHTMLTranslatorMixin
 
 logger = logging.getLogger(__name__)
@@ -82,15 +86,16 @@ def setup_domains(app, config):
     ``_hoverxref`` attributes.
     """
     # Add ``hoverxref`` role replicating the behavior of ``ref``
-    app.add_role_to_domain(
-        'std',
-        'hoverxref',
-        XRefRole(
-            lowercase=True,
-            innernodeclass=nodes.inline,
-            warn_dangling=True,
-        ),
-    )
+    for role in HoverXRefBaseDomain.hoverxref_types:
+        app.add_role_to_domain(
+            'std',
+            role,
+            XRefRole(
+                lowercase=True,
+                innernodeclass=nodes.inline,
+                warn_dangling=True,
+            ),
+        )
 
     domain = types.new_class(
         'HoverXRefStandardDomain',
@@ -176,9 +181,6 @@ def setup_theme(app, exception):
     Add a small custom CSS file for a specific theme and set hoverxref configs
     (if not overwritten by the user) with better defaults for these themes.
     """
-    if app.config.hoverxref_type != 'modal':
-        return
-
     css_file = None
     theme = app.config.html_theme
     default, rebuild, types = app.config.values.get('hoverxref_modal_class')
@@ -228,7 +230,7 @@ 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_type', 'tooltip', 'env')
+    app.add_config_value('hoverxref_default_type', 'tooltip', 'env')
     app.add_config_value('hoverxref_api_host', 'https://readthedocs.org', 'env')
 
     # Tooltipster settings
diff --git a/tests/test_htmltag.py b/tests/test_htmltag.py
@@ -74,7 +74,7 @@ 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 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="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>',
     ]
 
     for chunk in chunks:
@@ -123,7 +123,7 @@ def test_autosectionlabel_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 reference internal" data-doc="chapter-i" data-docpath="/chapter-i.html" data-project="myproject" data-section="chapter-i" data-version="myversion" href="chapter-i.html#chapter-i"><span class="std std-ref">This a :hoverxref: 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="chapter-i" data-version="myversion" href="chapter-i.html#chapter-i"><span class="std std-ref">This a :hoverxref: to Chapter I</span></a>',
     ]
 
     for chunk in chunks:
@@ -141,8 +141,8 @@ def test_custom_object(app, status, warning):
     content = open(path).read()
 
     chunks = [
-        '<a class="hoverxref 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 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="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>',
     ]
 
     for chunk in chunks:
@@ -162,9 +162,32 @@ def test_python_domain(app, status, warning):
     content = open(path).read()
 
     chunks = [
-        '<a class="hoverxref reference internal" data-doc="api" data-docpath="/api.html" data-project="myproject" data-section="hoverxref.extension.HoverXRefStandardDomainMixin" data-version="myversion" href="api.html#hoverxref.extension.HoverXRefStandardDomainMixin" title="hoverxref.extension.HoverXRefStandardDomainMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">This</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">:py:class:</span> <span class="pre">role</span> <span class="pre">to</span> <span class="pre">a</span> <span class="pre">Python</span> <span class="pre">object</span></code></a>',
-        '<a class="hoverxref reference internal" data-doc="api" data-docpath="/api.html" data-project="myproject" data-section="hoverxref.extension" data-version="myversion" href="api.html#module-hoverxref.extension" title="hoverxref.extension"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hoverxref.extension</span></code></a>',
-        '<a class="hoverxref reference internal" data-doc="api" data-docpath="/api.html" data-project="myproject" data-section="hoverxref.utils.get_ref_xref_data" data-version="myversion" href="api.html#hoverxref.utils.get_ref_xref_data" title="hoverxref.utils.get_ref_xref_data"><code class="xref py py-func docutils literal notranslate"><span class="pre">hoverxref.utils.get_ref_xref_data()</span></code></a>',
+        '<a class="hoverxref tooltip reference internal" data-doc="api" data-docpath="/api.html" data-project="myproject" data-section="hoverxref.extension.HoverXRefStandardDomainMixin" data-version="myversion" href="api.html#hoverxref.extension.HoverXRefStandardDomainMixin" title="hoverxref.extension.HoverXRefStandardDomainMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">This</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">:py:class:</span> <span class="pre">role</span> <span class="pre">to</span> <span class="pre">a</span> <span class="pre">Python</span> <span class="pre">object</span></code></a>',
+        '<a class="hoverxref tooltip reference internal" data-doc="api" data-docpath="/api.html" data-project="myproject" data-section="hoverxref.extension" data-version="myversion" href="api.html#module-hoverxref.extension" title="hoverxref.extension"><code class="xref py py-mod docutils literal notranslate"><span class="pre">hoverxref.extension</span></code></a>',
+        '<a class="hoverxref tooltip reference internal" data-doc="api" data-docpath="/api.html" data-project="myproject" data-section="hoverxref.utils.get_ref_xref_data" data-version="myversion" href="api.html#hoverxref.utils.get_ref_xref_data" title="hoverxref.utils.get_ref_xref_data"><code class="xref py py-func docutils literal notranslate"><span class="pre">hoverxref.utils.get_ref_xref_data()</span></code></a>',
+    ]
+
+    for chunk in chunks:
+        assert chunk in content
+
+
+@pytest.mark.sphinx(
+    srcdir=srcdir,
+    confoverrides={
+        'hoverxref_project': 'myproject',
+        'hoverxref_version': 'myversion',
+        'hoverxref_default_type': 'modal',
+    },
+)
+def test_project_version_settings(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="hoverxref modal 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>',
     ]
 
     for chunk in chunks:
