From d01e776c814a3f9eaa479ec7eb63fb4fc33a0143 Mon Sep 17 00:00:00 2001
From: Manuel Kaufmann <humitos@gmail.com>
Date: Thu, 6 May 2021 15:10:06 +0200
Subject: [PATCH] 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                |  3 +++
 sphinx/application.py  |  8 ++++++++
 sphinx/ext/mathjax.py  |  2 +-
 tests/test_ext_math.py | 13 +++++++++++++
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CHANGES b/CHANGES
index a71f25aaa..d970b7ec6 100644
--- a/CHANGES
+++ b/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
diff --git a/sphinx/application.py b/sphinx/application.py
index 4735beffd..59e1683b3 100644
--- a/sphinx/application.py
+++ b/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.
 
diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py
index 301c0d699..8fc63cb9e 100644
--- a/sphinx/ext/mathjax.py
+++ b/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:
diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py
index ebe2c0f38..52d49ec43 100644
--- a/tests/test_ext_math.py
+++ b/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