Add support for html_math_renderer = 'mathml'

Fixes #233.

docs/additional_samples.rst

@@ -209,7 +209,7 @@ Math
 
    .. math::
 
-      (a + b)^2 = a^2 + 2ab + b^2
+      (a + b)^2 = a^2 + 2ab + b^2 \\
 
       (a - b)^2 = a^2 - 2ab + b^2
 
@@ -225,10 +225,8 @@ Math
    .. math::
       :nowrap:
 
-      \begin{eqnarray}
          y    & = & ax^2 + bx + c \\
          f(x) & = & x^2 + 2xy + y^2
-      \end{eqnarray}
 
 
 

docs/conf.py

@@ -49,7 +49,6 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
-    "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx_immaterial.theme_result",
     "sphinx_immaterial.kbd_keys",
@@ -97,6 +96,7 @@
 html_title = "Sphinx-Immaterial"
 html_favicon = "_static/images/favicon.ico"  # colored version of material/bookshelf.svg
 html_logo = "_static/images/Ybin.gif"  # from https://gifer.com/en/Ybin
+html_math_renderer = "mathml"
 
 # -- HTML theme specific settings ------------------------------------------------
 

sphinx_immaterial/__init__.py

@@ -285,6 +285,8 @@ def setup(app: Sphinx):
         )
     app.add_html_theme("sphinx_immaterial", os.path.abspath(os.path.dirname(__file__)))
 
+    app.setup_extension("sphinx_immaterial.mathml_math_renderer")
+
     # register our custom directives/roles that are tied to this theme
     app.setup_extension("sphinx_immaterial.content_tabs")
     app.setup_extension("sphinx_immaterial.mermaid_diagrams")

sphinx_immaterial/mathml_math_renderer.py

@@ -0,0 +1,40 @@
+"""Extension that enables docutils' MathML-based math rendering."""
+
+import docutils.nodes
+import docutils.utils.math
+from docutils.writers._html_base import HTMLTranslator as BaseHTMLTranslator
+from sphinx.application import Sphinx
+
+# Sphinx overrides Docutils' math rendering.  Here, we override Sphinx's
+# override to revert to docutils' math rendering.
+
+
+def visit_math(self: BaseHTMLTranslator, node: docutils.nodes.math):
+    self.math_output = "mathml"
+    self.math_output_options = []
+    BaseHTMLTranslator.visit_math(self, node)
+
+
+def visit_math_block(self: BaseHTMLTranslator, node: docutils.nodes.math_block):
+    self.math_output = "mathml"
+    self.math_output_options = []
+    # Note: We can't call `BaseHTMLTranslator.visit_math_block` here, because
+    # that just forwards to `self.visit_math`, which ultimately calls back into
+    # our `visit_math` function defined above but without the `math_env`
+    # argument.
+    BaseHTMLTranslator.visit_math(
+        self, node, math_env=docutils.utils.math.pick_math_environment(node.astext())
+    )
+
+
+def setup(app: Sphinx):
+    """Setup the extension."""
+    app.add_html_math_renderer(
+        "mathml",
+        (visit_math, None),  # type: ignore[arg-type]
+        (visit_math_block, None),  # type: ignore[arg-type]
+    )
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }