Setup our own domains without override the existing one

Follow the same pattern for translators (#42) for domains.

Closes #14

Author: humitos

docs/usage.rst

@@ -68,11 +68,11 @@ An example using Python Domain would be like:
 
 .. code-block:: rst
 
-   :py:class:`hoverxref.domains.HoverXRefStandardDomain`
+   :py:class:`hoverxref.domains.HoverXRefStandardDomainMixin`
 
 That will render to:
 
-:py:class:`hoverxref.domains.HoverXRefStandardDomain`
+:py:class:`hoverxref.domains.HoverXRefStandardDomainMixin`
 
 
 To enable ``hoverxref`` on a domain, you need to use the config :confval:`hoverxref_domains`

hoverxref/domains.py

@@ -1,5 +1,3 @@
-from sphinx.domains.python import PythonDomain
-from sphinx.domains.std import StandardDomain
 from sphinx.util import logging
 from .utils import get_ref_xref_data, get_ref_obj_data
 
@@ -26,7 +24,7 @@ def _inject_hoverxref_data(self, env, refnode, docname, labelid):
         }
 
 
-class HoverXRefPythonDomain(HoverXRefBaseDomain, PythonDomain):
+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)
@@ -51,9 +49,9 @@ def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode):
         return refnode
 
 
-class HoverXRefStandardDomain(HoverXRefBaseDomain, StandardDomain):
+class HoverXRefStandardDomainMixin(HoverXRefBaseDomain):
     """
-    Override ``StandardDomain`` to save the values after the xref resolution.
+    Mixin for ``StandardDomain`` to save the values after the xref resolution.
 
     ``:ref:`` are treating as a different node in Sphinx
     (``sphinx.addnodes.pending_xref``). These nodes are translated to regular

hoverxref/extension.py

@@ -1,11 +1,12 @@
 import os
 import inspect
+import types
 from docutils import nodes
 from sphinx.roles import XRefRole
 from sphinx.util.fileutil import copy_asset
 
 from . import version
-from .domains import HoverXRefPythonDomain, HoverXRefStandardDomain
+from .domains import HoverXRefPythonDomainMixin, HoverXRefStandardDomainMixin
 from .translators import HoverXRefHTMLTranslator
 
 ASSETS_FILES = [
@@ -53,6 +54,13 @@ def copy_asset_files(app, exception):
 
 
 def setup_domains(app, config):
+    """
+    Override domains respecting the one defined (if any).
+
+    We create a new class by inheriting the Sphinx Domain already defined
+    and our own ``HoverXRef...DomainMixin`` that includes the logic for
+    ``_hoverxref`` attributes.
+    """
     # Add ``hoverxref`` role replicating the behavior of ``ref``
     app.add_role_to_domain(
         'std',
@@ -63,10 +71,27 @@ def setup_domains(app, config):
             warn_dangling=True,
         ),
     )
-    app.add_domain(HoverXRefStandardDomain, override=True)
 
-    if 'py' in config.hoverxref_domains:
-        app.add_domain(HoverXRefPythonDomain, override=True)
+    domain = types.new_class(
+        'HoverXRefStandardDomain',
+        (
+            HoverXRefStandardDomainMixin,
+            app.registry.domains.get('std'),
+        ),
+        {}
+    )
+    app.add_domain(domain, override=True)
+
+    if 'py' in app.config.hoverxref_domains:
+        domain = types.new_class(
+            'HoverXRefPythonDomain',
+            (
+                HoverXRefPythonDomainMixin,
+                app.registry.domains.get('py'),
+            ),
+            {}
+        )
+        app.add_domain(domain, override=True)
 
 
 def setup_sphinx_tabs(app, config):

tests/examples/python-domain/api.rst

@@ -3,7 +3,7 @@
 API
 ===
 
-.. autoclass:: hoverxref.extension.HoverXRefStandardDomain
+.. autoclass:: hoverxref.extension.HoverXRefStandardDomainMixin
 
 
 .. automodule:: hoverxref.extension

tests/examples/python-domain/index.rst

@@ -3,7 +3,7 @@ Python Domain
 
 This is an example page with a Python Domain role usage.
 
-:py:class:`This is a :py:class: role to a Python object <hoverxref.extension.HoverXRefStandardDomain>`.
+:py:class:`This is a :py:class: role to a Python object <hoverxref.extension.HoverXRefStandardDomainMixin>`.
 
 :py:mod:`hoverxref.extension`
 

tests/test_htmltag.py

@@ -162,7 +162,7 @@ def test_python_domain(app, status, warning):
     content = open(path).read()
 
     chunks = [
-        '<a class="hoverxref reference internal" data-doc="api" data-project="myproject" data-section="hoverxref.extension.HoverXRefStandardDomain" data-version="myversion" href="api.html#hoverxref.extension.HoverXRefStandardDomain" title="hoverxref.extension.HoverXRefStandardDomain"><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-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-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-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>',
     ]