From e2c6146b3eddd29851334f5536f8d9f90a9eef36 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 18 Nov 2021 02:03:43 +0900 Subject: [PATCH 1/2] Fix #9864: mathjax: Failed to render equations via MathJax v2 MathJax library has been loaded via "defer" method since v4.3.0. But it prevents to work MathJax v2. This rollbacks the change and use "async" method as default again. To support changing the loading method, this allows to specify it via mathjax_options. --- CHANGES | 5 +++++ doc/usage/extensions/math.rst | 5 +++++ sphinx/ext/mathjax.py | 12 ++++++++++-- tests/test_ext_math.py | 28 ++++++++++++++++++++++++++-- 4 files changed, 46 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index 4ee8d55cd91..ad24bb10579 100644 --- a/CHANGES +++ b/CHANGES @@ -13,11 +13,16 @@ Deprecated Features added -------------- +* #9864: mathjax: Support chnaging the loading method of MathJax to "defer" via + :confval:`mathjax_options` + Bugs fixed ---------- * #9838: autodoc: AttributeError is raised on building document for functions decorated by functools.lru_cache +* #9864: mathjax: Failed to render equations via MathJax v2. The loading method + of MathJax is back to "async" method again Testing -------- diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 764bf5dd3ed..62630608993 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -200,6 +200,11 @@ Sphinx but is set to automatically include it from a third-party site. .. versionadded:: 1.8 + .. versionchanged:: 4.4.1 + + Allow to change the loading method (async or defer) of MathJax if "async" + or "defer" key is set. + .. confval:: mathjax3_config The configuration options for MathJax v3 (which is used by default). diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py index eb06908d30e..0d112895457 100644 --- a/sphinx/ext/mathjax.py +++ b/sphinx/ext/mathjax.py @@ -81,10 +81,18 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict domain = cast(MathDomain, app.env.get_domain('math')) if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename): # Enable mathjax only if equations exists - options = {'defer': 'defer'} + options = {} if app.config.mathjax_options: options.update(app.config.mathjax_options) - app.add_js_file(app.config.mathjax_path, **options) # type: ignore + if 'async' not in options and 'defer' not in options: + print(options, app.config.mathjax3_config) + if app.config.mathjax3_config: + # Load MathJax v3 via "defer" method + options['defer'] = 'defer' + else: + # Load other MathJax via "async" method + options['async'] = 'async' + app.add_js_file(app.config.mathjax_path, **options) if app.config.mathjax2_config: if app.config.mathjax_path == MATHJAX_URL: diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py index 7c78954b7ff..175c9e0f569 100644 --- a/tests/test_ext_math.py +++ b/tests/test_ext_math.py @@ -71,7 +71,7 @@ def test_mathjax_options(app, status, warning): app.builder.build_all() content = (app.outdir / 'index.html').read_text() - assert ('' in content) @@ -221,6 +221,7 @@ def test_mathjax3_config(app, status, warning): content = (app.outdir / 'index.html').read_text() assert MATHJAX_URL in content + assert ('' in content) @@ -231,12 +232,35 @@ def test_mathjax2_config(app, status, warning): app.builder.build_all() content = (app.outdir / 'index.html').read_text() - assert MATHJAX_URL in content + assert ('' in content) +@pytest.mark.sphinx('html', testroot='ext-math', + confoverrides={'extensions': ['sphinx.ext.mathjax'], + 'mathjax_options': {'async': 'async'}, + 'mathjax3_config': {'extensions': ['tex2jax.js']}}) +def test_mathjax_options_async_for_mathjax3(app, status, warning): + app.builder.build_all() + + content = (app.outdir / 'index.html').read_text() + assert MATHJAX_URL in content + assert ('