Setup our own translator without override the existing one

Instead of fully override the translator set by the user (or another
Sphinx extension), we create a new class dynamically by inheriting the
translator that's defined and adding our own Mixin class with our
custom behavior.

This way, we are compatible with other extensions nicely.

As a example, I tested this with
pydata-sphinx-theme (https://github.com/pandas-dev/pydata-sphinx-theme)
that defines a custom translator.

Besides, this new approach is compatible with people using HTML5
translator by default since we are not forcing HTML4 when inheriting
our own custom class anymore.

Author: humitos

hoverxref/extension.py

@@ -1,12 +1,13 @@
 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 .translators import HoverXRefHTMLTranslator
+from .translators import HoverXRefHTMLTranslatorMixin
 
 ASSETS_FILES = [
     'js/hoverxref.js_t',  # ``_t`` tells Sphinx this is a template
@@ -83,6 +84,47 @@ def setup_sphinx_tabs(app, config):
             app.disconnect(listener_id)
 
 
+def setup_translators(app):
+    """
+    Override translators respecting the one defined.
+
+    We create a new class by inheriting the Sphinx Translator already defined
+    and our own ``HoverXRefHTMLTranslatorMixin`` that includes the logic to
+    ``_hoverxref`` attributes.
+
+    User's defined translator has to be added with ``override=True``. Otherwise,
+    Sphinx fails with an error.
+    """
+    if not app.registry.translators.items():
+        translator = types.new_class(
+            'HoverXRefHTMLTranslator',
+            (
+                HoverXRefHTMLTranslatorMixin,
+                app.builder.default_translator_class,
+            ),
+            {},
+        )
+        app.set_translator(app.builder.name, translator, override=True)
+    else:
+        for name, klass in app.registry.translators.items():
+            # Read the Docs use ``readthedocs`` as the name of the build, so we
+            # need to replace this as well
+            if name not in ['html', 'readthedocs', 'readthedocsdirhtml']:
+                # Skip translator that are not HTML
+                continue
+
+            translator = types.new_class(
+                'HoverXRefHTMLTranslator',
+                (
+                    HoverXRefHTMLTranslatorMixin,
+                    klass,
+                ),
+                {},
+            )
+            app.set_translator(name, translator, override=True)
+
+
+
 def setup(app):
     """Setup ``hoverxref`` Sphinx extension."""
 
@@ -109,13 +151,7 @@ def setup(app):
     app.add_config_value('hoverxref_tooltip_content', 'Loading...', 'env')
     app.add_config_value('hoverxref_tooltip_class', 'rst-content', 'env')
 
-    app.set_translator('html', HoverXRefHTMLTranslator, override=True)
-
-    # Read the Docs use ``readthedocs`` as the name of the build, so we need to
-    # replace this as well
-    app.set_translator('readthedocs', HoverXRefHTMLTranslator, override=True)
-    app.set_translator('readthedocsdirhtml', HoverXRefHTMLTranslator, override=True)
-
+    app.connect('builder-inited', setup_translators)
     app.connect('config-inited', setup_domains)
     app.connect('config-inited', setup_sphinx_tabs)
     app.connect('build-finished', copy_asset_files)

hoverxref/translators.py

@@ -1,13 +1,12 @@
-from sphinx.writers.html import HTMLTranslator
 from sphinx.util import logging
 
 logger = logging.getLogger(__name__)
 
 
-class HoverXRefHTMLTranslator(HTMLTranslator):
+class HoverXRefHTMLTranslatorMixin:
 
     """
-    Override ``HTMLTranslator`` to render extra data saved in reference nodes.
+    Mixin ``HTMLTranslator`` to render extra data saved in reference nodes.
 
     It adds all the values saved under ``_hoverxref`` as attributes of the HTML
     reference tag.