Fix the lazy loading conditions for MathJax (sphinx-doc#11597)

Co-authored-by: Adam Turner <[email protected]>

CHANGES.rst

@@ -29,6 +29,11 @@ Bugs fixed
   Patch by Bénédikt Tran.
 * #11666: Skip all hidden directories in ``CatalogRepository.pofiles``.
   Patch by Aryaz Eghbali.
+* #9686: html builder: Fix MathJax lazy loading when equations appear in titles.
+  Patch by Bénédikt Tran.
+* #11483: singlehtml builder: Fix MathJax lazy loading when the index does not
+  contain any math equations.
+  Patch by Bénédikt Tran.
 
 Testing
 -------

sphinx/domains/math.py

@@ -134,11 +134,14 @@ def get_objects(self) -> Iterable[tuple[str, str, str, str, str, int]]:
         return []
 
     def has_equations(self, docname: str | None = None) -> bool:
-        if docname:
-            return self.data['has_equations'].get(docname, False)
-        else:
+        if not docname:
             return any(self.data['has_equations'].values())
 
+        return (
+            self.data['has_equations'].get(docname, False)
+            or any(map(self.has_equations, self.env.toctree_includes.get(docname, ())))
+        )
+
 
 def setup(app: Sphinx) -> dict[str, Any]:
     app.add_domain(MathDomain)

tests/roots/test-ext-math-include/included.rst

@@ -0,0 +1,6 @@
+Title
+=====
+
+Some file including some maths.
+
+.. include:: math.rst

tests/roots/test-ext-math-include/index.rst

@@ -0,0 +1,7 @@
+Test Math
+=========
+
+.. toctree::
+   :numbered: 1
+
+   included

tests/roots/test-ext-math-include/math.rst

@@ -0,0 +1,4 @@
+:math:`1 + 1 = 2`
+=================
+
+Lorem ipsum.

tests/test_ext_math.py

@@ -343,3 +343,47 @@ def test_mathjax_is_installed_if_no_equations_when_forced(app, status, warning):
 
     content = (app.outdir / 'nomath.html').read_text(encoding='utf8')
     assert MATHJAX_URL in content
+
+
+@pytest.mark.sphinx('html', testroot='ext-math-include',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax']})
+def test_mathjax_is_installed_if_included_file_has_equations(app):
+    app.builder.build_all()
+
+    # no real equations at the rst level, but includes "included"
+    content = (app.outdir / 'index.html').read_text(encoding='utf8')
+    assert MATHJAX_URL in content
+
+    # no real equations at the rst level, but includes "math.rst"
+    content = (app.outdir / 'included.html').read_text(encoding='utf8')
+    assert MATHJAX_URL in content
+
+    content = (app.outdir / 'math.html').read_text(encoding='utf8')
+    assert MATHJAX_URL in content
+
+
+@pytest.mark.sphinx('singlehtml', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax']})
+def test_mathjax_is_installed_only_if_document_having_math_singlehtml(app):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text(encoding='utf8')
+    assert MATHJAX_URL in content
+
+
+@pytest.mark.sphinx('singlehtml', testroot='basic',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax']})
+def test_mathjax_is_not_installed_if_no_equations_singlehtml(app):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text(encoding='utf8')
+    assert 'MathJax.js' not in content
+
+
+@pytest.mark.sphinx('singlehtml', testroot='ext-math-include',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax']})
+def test_mathjax_is_installed_if_included_file_has_equations_singlehtml(app):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text(encoding='utf8')
+    assert MATHJAX_URL in content