Merge pull request #9094 from mgeier/mathjax3_config

Add `mathjax3_config` config option

CHANGES

@@ -47,6 +47,8 @@ Features added
 * #9103: LaTeX: imgconverter: conversion runs even if not needed
 * #8127: py domain: Ellipsis in info-field-list causes nit-picky warning
 * #9023: More CSS classes on domain descriptions, see :ref:`nodes` for details.
+* #8195: mathjax: Rename :confval:`mathjax_config` to
+  :confval:`mathjax2_config` and add :confval:`mathjax3_config`
 
 Bugs fixed
 ----------

doc/usage/extensions/math.rst

@@ -144,7 +144,8 @@ are built:
    Version 4.0 changes the version of MathJax used to version 3. You may need to
    override ``mathjax_path`` to
    ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML``
-   or update your configuration options for version 3.
+   or update your configuration options for version 3
+   (see :confval:`mathjax3_config`).
 
 .. versionadded:: 1.1
 
@@ -199,24 +200,58 @@ Sphinx but is set to automatically include it from a third-party site.
 
    .. versionadded:: 1.8
 
-.. confval:: mathjax_config
+.. confval:: mathjax3_config
 
-   The inline configuration options for mathjax.  The value is used as a
-   parameter of ``MathJax.Hub.Config()``.  For more information, please
-   read `Using in-line configuration options`_.
+   The configuration options for MathJax v3 (which is used by default).
+   The given dictionary is assigned to the JavaScript variable
+   ``window.MathJax``.
+   For more information, please read `Configuring MathJax`__.
+
+   __ https://docs.mathjax.org/en/latest/web/configuration.html#configuration
+
+   The default is empty (not configured).
+
+   .. versionadded:: 4.0
+
+.. confval:: mathjax2_config
+
+   The configuration options for MathJax v2 (which can be loaded via
+   :confval:`mathjax_path`).
+   The value is used as a parameter of ``MathJax.Hub.Config()``.
+   For more information, please read `Using in-line configuration options`__.
+
+   __ http://docs.mathjax.org/en/v2.7-latest/
+      configuration.html#using-in-line-configuration-options
 
    For example::
 
-       mathjax_config = {
+       mathjax2_config = {
            'extensions': ['tex2jax.js'],
            'jax': ['input/TeX', 'output/HTML-CSS'],
        }
 
    The default is empty (not configured).
 
+   .. versionadded:: 4.0
+
+      :confval:`mathjax_config` has been renamed to :confval:`mathjax2_config`.
+
+.. confval:: mathjax_config
+
+   Former name of :confval:`mathjax2_config`.
+
+   For help converting your old MathJax configuration to to the new
+   :confval:`mathjax3_config`, see `Converting Your v2 Configuration to v3`__.
+
+   __ https://docs.mathjax.org/en/latest/web/
+      configuration.html#converting-your-v2-configuration-to-v3
+
    .. versionadded:: 1.8
 
-.. _Using in-line configuration options: https://docs.mathjax.org/en/latest/configuration.html#using-in-line-configuration-options
+   .. versionchanged:: 4.0
+
+      This has been renamed to :confval:`mathjax2_config`.
+      :confval:`mathjax_config` is still supported for backwards compatibility.
 
 :mod:`sphinx.ext.jsmath` -- Render math via JavaScript
 ------------------------------------------------------

sphinx/ext/mathjax.py

@@ -27,6 +27,8 @@ from sphinx.writers.html import HTMLTranslator
 # https://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn
 MATHJAX_URL = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
 
+logger = sphinx.util.logging.getLogger(__name__)
+
 
 def html_visit_math(self: HTMLTranslator, node: nodes.math) -> None:
     self.body.append(self.starttag(node, 'span', '', CLASS='math notranslate nohighlight'))
@@ -84,9 +86,16 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict
             options.update(app.config.mathjax_options)
         app.add_js_file(app.config.mathjax_path, **options)  # type: ignore
 
-        if app.config.mathjax_config:
-            body = "MathJax.Hub.Config(%s)" % json.dumps(app.config.mathjax_config)
-            app.add_js_file(None, type="text/x-mathjax-config", body=body)
+        if app.config.mathjax2_config:
+            if app.config.mathjax_path == MATHJAX_URL:
+                logger.warning(
+                    'mathjax_config/mathjax2_config does not work '
+                    'for the current MathJax version, use mathjax3_config instead')
+            body = 'MathJax.Hub.Config(%s)' % json.dumps(app.config.mathjax2_config)
+            app.add_js_file(None, type='text/x-mathjax-config', body=body)
+        if app.config.mathjax3_config:
+            body = 'window.MathJax = %s' % json.dumps(app.config.mathjax3_config)
+            app.add_js_file(None, body=body)
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
@@ -99,6 +108,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
     app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')
     app.add_config_value('mathjax_config', None, 'html')
+    app.add_config_value('mathjax2_config', lambda c: c.mathjax_config, 'html')
+    app.add_config_value('mathjax3_config', None, 'html')
     app.connect('html-page-context', install_mathjax)
 
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}