Config to add JS/CSS to all generated HTML pages

[humitos]

Is your feature request related to a problem? Please describe.

After #8631 was merged, JS/CSS files for MathJax are only added to those pages that contains math formulas. This is not a problem unless you want to embed the content of one of those pages where the JS/CSS are included from a different page.

This problem is clear on my extension sphinx-hoverxref that shows a tooltip with the content of the linked page when hovering over a link. Example: if you hover on "tooltip with Mathjax" in https://sphinx-hoverxref.readthedocs.io/en/sphinx-35/usage.html#tooltip-with-mathjax you won't see the MathJax rendered properly inside the tooltip

and an error in the console "Not triggering MathJax because it is not defined". This is because MathJax is not included in usage.html page but it's included in target page (mathjax.html)

Note that I'm mentioning the problem only with MathJax for now since it's a known extension that it's using this new feature, but this applies to all the extension that start including the JS/CSS only on pages where the extension is present

Describe the solution you'd like

I think a config to force the old behavior that includes all the JS/CSS in all the pages could work. I know this has some drawbacks, but as far is optional, I think it's good.

Describe alternatives you've considered

1. sphinx-hoverxref uses an endpoint from Read the Docs' API to get the content to embed in the tooltip. We are discussing if it's possible to return "extras": ["mathjax.js", "mathjax.css"] together with the content to be included so the JS client knows it has to include these assets before rendering the content. See Embed: design doc for new embed API readthedocs/readthedocs.org#8039 (comment)
2. Another option could be to detect from the Sphinx extension "what are the assets required in the target page and add them into this page as well". Note that this won't work when using intersphinx.

Additional context

Reference: #8631 (comment)
Downstream issue: readthedocs/sphinx-hoverxref#119

[tk0miya]

My thought:

• Only extensions would like to enable JS/CSS in the all pages. Users would not. So it's better to provide an API to switch the behavior instead of a configuration.
• It's difficult to control the behavior by sphinx-core because extensions can control the visibility of the JS/CSS on their code, not sphinx-core.
  Here is an example of mathjax's case. It enables JS entry only if the document contains equations at least one.
  

  sphinx/sphinx/ext/mathjax.py

  Lines 82 to 98 in 4e9d155

  	if domain.has_equations(pagename):
  	# Enable mathjax only if equations exists
  	options = {'async': 'async'}
  	if app.config.mathjax_options:
  	options.update(app.config.mathjax_options)
  	app.add_js_file(app.config.mathjax_path, **options) # type: ignore
  	if app.config.mathjax2_config:
  	if app.config.mathjax_path == MATHJAX_URL:
  	logger.warning(
  	'mathjax_config/mathjax2_config does not work '
  	'for the current MathJax version, use mathjax3_config instead')
  	body = 'MathJax.Hub.Config(%s)' % json.dumps(app.config.mathjax2_config)
  	app.add_js_file(None, type='text/x-mathjax-config', body=body)
  	if app.config.mathjax3_config:
  	body = 'window.MathJax = %s' % json.dumps(app.config.mathjax3_config)
  	app.add_js_file(None, body=body)

• So the following mechanism is needed to resolve this problem:
  • A new API like app.enable_html_assets_in_all_pages() to enable assets in all pages.
  • Extensions should refer the result of the API to control when they install assets in the specific pages.

[mgeier]

BTW, a similar thing happens if there is :math:`a+b` in a page title, it will not be displayed in the TOC of other pages (if those don't use any math on their own).

I'm not sure if this should be a separate issue.
This is something that happens in Sphinx core, without extensions (except for sphinx.ext.mathjax).

[tk0miya]

It's a different topic. And it was already posted as #8139.

[humitos]

Thanks for sharing your thoughts @tk0miya! I think adding something like app.enable_html_assets_in_all_pages() is a good path forward. I understand the result of that would be able to be changed by one extension so all the other ones follow that rule, right? I imagine that if any extension defines enable_html_assets_in_all_pages = True every other extension will add assets to all the pages even if there is one extension that defines enable_html_assets_in_all_pages = False. So, True takes precedence.

[humitos]

@tk0miya I opened a PR with a proposal. Let's see if that's something similar to what you had in mind. Let me know 😄