From 436519743baa70b16ecc881ccadc40ce6ec83fba Mon Sep 17 00:00:00 2001 From: Hameer Abbasi Date: Wed, 15 Jul 2020 12:39:22 +0200 Subject: [PATCH 1/6] Move to MathJax 3. --- doc/usage/extensions/math.rst | 8 ++++++-- sphinx/ext/mathjax.py | 4 ++-- tests/test_ext_math.py | 4 ++-- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 780e57ee29d..62d8603c9ee 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -140,6 +140,10 @@ are built: .. module:: sphinx.ext.mathjax :synopsis: Render math using JavaScript via MathJax. +.. warning:: + Version 4.0 changes the version of MathJax used to version 3. You may need to + to override ``mathjax_path`` or change your configuration options. + .. versionadded:: 1.1 This extension puts math as-is into the HTML files. The JavaScript package @@ -161,12 +165,12 @@ Sphinx but is set to automatically include it from a third-party site. MathJax. The default is the ``https://`` URL that loads the JS files from the - `cdnjs`__ Content Delivery Network. See the `MathJax Getting Started + `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started page`__ for details. If you want MathJax to be available offline or without including resources from a third-party site, you have to download it and set this value to a different path. - __ https://cdnjs.com + __ https://www.jsdelivr.com/ __ https://docs.mathjax.org/en/latest/start.html diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py index cc3cd4ba34e..59eb160472e 100644 --- a/sphinx/ext/mathjax.py +++ b/sphinx/ext/mathjax.py @@ -96,8 +96,8 @@ def setup(app: Sphinx) -> Dict[str, Any]: # more information for mathjax secure url is here: # https://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn app.add_config_value('mathjax_path', - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?' - 'config=TeX-AMS-MML_HTMLorMML', 'html') + 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js', + 'html') app.add_config_value('mathjax_options', {}, 'html') app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html') app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html') diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py index 4df7d47c7c2..d094def7ae7 100644 --- a/tests/test_ext_math.py +++ b/tests/test_ext_math.py @@ -71,8 +71,8 @@ def test_mathjax_options(app, status, warning): content = (app.outdir / 'index.html').read_text() assert ('' in content) + 'src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">' + '' in content) @pytest.mark.sphinx('html', testroot='ext-math', From 72f359279684b931180414e6d7bf653774a6cf8e Mon Sep 17 00:00:00 2001 From: Hameer Abbasi Date: Wed, 15 Jul 2020 14:39:56 +0200 Subject: [PATCH 2/6] Delete repeated word. Co-authored-by: Dmitry Shachnev --- doc/usage/extensions/math.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 62d8603c9ee..91cb451248c 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -142,7 +142,7 @@ are built: .. warning:: Version 4.0 changes the version of MathJax used to version 3. You may need to - to override ``mathjax_path`` or change your configuration options. + override ``mathjax_path`` or change your configuration options. .. versionadded:: 1.1 From 882376886bc81d3977ebcd47d1be58a7fe671cb3 Mon Sep 17 00:00:00 2001 From: Hameer Abbasi Date: Thu, 16 Jul 2020 12:07:46 +0200 Subject: [PATCH 3/6] Add changes entry. --- CHANGES | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES b/CHANGES index 38c18256d95..1393ae8adbe 100644 --- a/CHANGES +++ b/CHANGES @@ -12,6 +12,9 @@ Incompatible changes * #4826: py domain: The structure of python objects is changed. A boolean value is added to indicate that the python object is canonical one +* #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom + MathJax configuration may have to set the old MathJax path or update their + configuration for version 3. Deprecated ---------- From aed8f719ca9a2657cd37ae674f7f7ff67d5d24e1 Mon Sep 17 00:00:00 2001 From: Hameer Abbasi Date: Fri, 24 Jul 2020 11:52:30 +0200 Subject: [PATCH 4/6] Expand warning and refer to it from CHANGES. --- CHANGES | 2 +- doc/usage/extensions/math.rst | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 1393ae8adbe..23dae4c1380 100644 --- a/CHANGES +++ b/CHANGES @@ -14,7 +14,7 @@ Incompatible changes is added to indicate that the python object is canonical one * #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom MathJax configuration may have to set the old MathJax path or update their - configuration for version 3. + configuration for version 3. See :mod:`sphinx.ext.mathjax`. Deprecated ---------- diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 91cb451248c..ff860bd379a 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -142,7 +142,8 @@ are built: .. warning:: Version 4.0 changes the version of MathJax used to version 3. You may need to - override ``mathjax_path`` or change your configuration options. + override ``mathjax_path`` to ``https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML`` + or update your configuration options for version 3. .. versionadded:: 1.1 @@ -172,7 +173,7 @@ Sphinx but is set to automatically include it from a third-party site. __ https://www.jsdelivr.com/ - __ https://docs.mathjax.org/en/latest/start.html + __ https://www.mathjax.org/#gettingstarted The path can be absolute or relative; if it is relative, it is relative to the ``_static`` directory of the built docs. From 496ac3fe8bd8c81c569a31b25c0a1a9e536e94d7 Mon Sep 17 00:00:00 2001 From: Hameer Abbasi Date: Fri, 24 Jul 2020 12:31:23 +0200 Subject: [PATCH 5/6] Change MathJax 2 path string. Co-authored-by: Dmitry Shachnev --- doc/usage/extensions/math.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index ff860bd379a..648e4ab6bc1 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -142,7 +142,7 @@ are built: .. warning:: Version 4.0 changes the version of MathJax used to version 3. You may need to - override ``mathjax_path`` to ``https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML`` + 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. .. versionadded:: 1.1 From 8f5ce152a134415bc1604740bcf397c7f124fdf7 Mon Sep 17 00:00:00 2001 From: Hameer Abbasi Date: Fri, 24 Jul 2020 16:59:40 +0200 Subject: [PATCH 6/6] Fold line. --- doc/usage/extensions/math.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index ff860bd379a..dec64c8cd12 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -142,7 +142,8 @@ are built: .. warning:: Version 4.0 changes the version of MathJax used to version 3. You may need to - override ``mathjax_path`` to ``https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML`` + override ``mathjax_path`` to + ``https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML`` or update your configuration options for version 3. .. versionadded:: 1.1