Add Sphinx.add_html_assets_in_all_pages

This new method in the `Sphinx` object allows extensions to communicate to
Sphinx that it's preferred to include HTML assets in all the pages. However,
it's extensions developers' responsability to follow this config and decide
whether or not include the assets required.

Extensions developers' can check `Sphinx.html_assets_in_all_pages` together with
any other logic they may have to decide if the assets will be included in the
rendered page or not.

Closes #9115

CHANGES

@@ -30,6 +30,9 @@ Features added
 * #9097: Optimize the paralell build
 * #9131: Add :confval:`nitpick_ignore_regex` to ignore nitpicky warnings using
   regular expressions
+* #9174: Add ``Sphinx.add_html_assets_in_all_pages`` to tell extensions to include
+  HTML assets in all the pages. Extensions can check this via
+  ``Sphinx.html_assets_in_all_pages``
 
 
 Bugs fixed

sphinx/application.py

@@ -146,6 +146,7 @@ class Sphinx:
         self.project: Project = None
         self.registry = SphinxComponentRegistry()
         self.html_themes: Dict[str, str] = {}
+        self.html_assets_in_all_pages: bool = False
 
         # validate provided directories
         self.srcdir = abspath(srcdir)
@@ -1181,6 +1182,13 @@ class Sphinx:
         logger.debug('[app] adding environment collector: %r', collector)
         collector().enable(self)
 
+    def add_html_assets_in_all_pages(self):
+        """Tell extensions to insert HTML assets in all the pages.
+
+        .. versionadded: 4.1
+        """
+        self.html_assets_in_all_pages = True
+
     def add_html_theme(self, name: str, theme_path: str) -> None:
         """Register a HTML Theme.
 

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.html_assets_in_all_pages or domain.has_equations(pagename):
         # Enable mathjax only if equations exists
         options = {'async': 'async'}
         if app.config.mathjax_options:

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.add_html_assets_in_all_pages()
+    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