Add Sphinx.add_html_assets_in_all_pages

CHANGES

@@ -55,6 +55,9 @@ Features added
 * #9097: Optimize the paralell build
 * #9131: Add :confval:`nitpick_ignore_regex` to ignore nitpicky warnings using
   regular expressions
+* #9174: Add ``Sphinx.set_html_assets_policy`` to tell extensions to include
+  HTML assets in all the pages. Extensions can check this via
+  ``Sphinx.registry.html_assets_policy``
 * C++, add support for
 
   - ``inline`` variables,

sphinx/application.py

@@ -1250,6 +1250,18 @@ def is_parallel_allowed(self, typ: str) -> bool:
 
         return True
 
+    def set_html_assets_policy(self, policy):
+        """Set the policy to include assets in HTML pages.
+
+        - always: include the assets in all the pages
+        - per_page: include the assets only in pages where they are used
+
+        .. versionadded: 4.1
+        """
+        if policy not in ('always', 'per_page'):
+            raise ValueError('policy %s is not supported' % policy)
+        self.registry.html_assets_policy = policy
+
     @property
     def html_themes(self) -> Dict[str, str]:
         warnings.warn('app.html_themes is deprecated.',

sphinx/ext/mathjax.py

@@ -79,7 +79,7 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict
                              'mathjax extension to work')
 
     domain = cast(MathDomain, app.env.get_domain('math'))
-    if domain.has_equations(pagename):
+    if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
         # Enable mathjax only if equations exists
         options = {'async': 'async'}
         if app.config.mathjax_options:

sphinx/registry.py

@@ -93,6 +93,9 @@ def __init__(self) -> None:
         self.html_inline_math_renderers: Dict[str, Tuple[Callable, Callable]] = {}
         self.html_block_math_renderers: Dict[str, Tuple[Callable, Callable]] = {}
 
+        #: HTML assets
+        self.html_assets_policy: str = 'per_page'
+
         #: HTML themes
         self.html_themes: Dict[str, str] = {}
 

tests/test_ext_math.py

@@ -256,3 +256,16 @@ def test_mathjax_is_not_installed_if_no_equations(app, status, warning):
 
     content = (app.outdir / 'index.html').read_text()
     assert 'MathJax.js' not in content
+
+
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax']})
+def test_mathjax_is_installed_if_no_equations_when_forced(app, status, warning):
+    app.set_html_assets_policy('always')
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text()
+    assert MATHJAX_URL in content
+
+    content = (app.outdir / 'nomath.html').read_text()
+    assert MATHJAX_URL in content