ENH/MAINT: avoid overwriting the HtmlTranslator (#1105)

Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>
Fix #143
Fix #94

src/pydata_sphinx_theme/__init__.py

@@ -6,6 +6,7 @@
 from functools import lru_cache
 import json
 from urllib.parse import urlparse, urlunparse
+import types
 
 import jinja2
 from bs4 import BeautifulSoup as bs
@@ -22,7 +23,7 @@
 import requests
 from requests.exceptions import ConnectionError, HTTPError, RetryError
 
-from .bootstrap_html_translator import BootstrapHTML5Translator
+from .translator import BootstrapHTML5TranslatorMixin
 
 __version__ = "0.12.1rc1.dev0"
 
@@ -1047,6 +1048,42 @@ def parse_url(self, uri):
         return text
 
 
+def setup_translators(app):
+    """
+    Add bootstrap HTML functionality if we are using an HTML translator.
+
+    This re-uses the pre-existing Sphinx translator and adds extra functionality defined
+    in ``BootstrapHTML5TranslatorMixin``. This way we can retain the original translator's
+    behavior and configuration, and _only_ add the extra bootstrap rules.
+    If we don't detect an HTML-based translator, then we do nothing.
+    """
+    if not app.registry.translators.items():
+        translator = types.new_class(
+            "BootstrapHTML5Translator",
+            (
+                BootstrapHTML5TranslatorMixin,
+                app.builder.default_translator_class,
+            ),
+            {},
+        )
+        app.set_translator(app.builder.name, translator, override=True)
+    else:
+        for name, klass in app.registry.translators.items():
+            if app.builder.format != "html":
+                # Skip translators that are not HTML
+                continue
+
+            translator = types.new_class(
+                "BootstrapHTML5Translator",
+                (
+                    BootstrapHTML5TranslatorMixin,
+                    klass,
+                ),
+                {},
+            )
+            app.set_translator(name, translator, override=True)
+
+
 # -----------------------------------------------------------------------------
 
 
@@ -1058,13 +1095,7 @@ def setup(app):
 
     app.add_post_transform(ShortenLinkTransform)
 
-    app.set_translator("html", BootstrapHTML5Translator)
-    # Read the Docs uses ``readthedocs`` as the name of the build, and also
-    # uses a special "dirhtml" builder so we need to replace these both with
-    # our custom HTML builder
-    app.set_translator("readthedocs", BootstrapHTML5Translator, override=True)
-    app.set_translator("readthedocsdirhtml", BootstrapHTML5Translator, override=True)
-
+    app.connect("builder-inited", setup_translators)
     app.connect("builder-inited", update_config)
     app.connect("html-page-context", setup_edit_url)
     app.connect("html-page-context", add_toctree_functions)

src/pydata_sphinx_theme/bootstrap_html_translator.py → src/pydata_sphinx_theme/translator.py

@@ -1,18 +1,18 @@
-"""A custom Sphinx HTML Translator for Bootstrap layout
+"""
+A custom Sphinx HTML Translator for Bootstrap layout
 """
 from packaging.version import Version
 
 import sphinx
-from sphinx.writers.html5 import HTML5Translator
 from sphinx.util import logging
 from sphinx.ext.autosummary import autosummary_table
 
 logger = logging.getLogger(__name__)
 
 
-class BootstrapHTML5Translator(HTML5Translator):
-    """Custom HTML Translator for a Bootstrap-ified Sphinx layout
-    This is a specialization of the HTML5 Translator of sphinx.
+class BootstrapHTML5TranslatorMixin:
+    """
+    Mixin HTML Translator for a Bootstrap-ified Sphinx layout.
     Only a couple of functions have been overridden to produce valid HTML to be
     directly styled with Bootstrap, and fulfill acessibility best practices.
     """