Close #6241: html: Allow to add JS/CSS files to the specific page

[tk0miya]

Feature or Bugfix

• Feature

Purpose

• Allow to add JS/CSS files to the specific page when an extension calls
  app.add_js_file() or app.add_css_file() on html-context-page
  event.
• refs: Include Mathjax.js on per-page basis #6241

[choldgraf]

Does this happen purely "under the hood" (AKA without any extra user configuration) as long as add_js_file is used within the html context event rather than an earlier event? So that:

• add_js_file and add_css_file before html-page-context will apply to all pages
• the same methods called within html-page-context will only apply to the current page

Is that right?

If so, I think this is awesome :-)

Also - maybe this should be documented here: https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-page-context ?

[tk0miya]

Yes, you're right.

Also - maybe this should be documented here: https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-page-context ?

Thanks. I'll update it too.

[choldgraf]

Should probably also be mentioned here:

• https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file
• https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file

(or cross-referenced). Otherwise I suspect users will be confused when there's different behavior based on context that isn't documented

[tk0miya]

Should probably also be mentioned here:

We're using autodoc to build out document. So the docstrings are automatically applied to the docs.

[akhmerov]

I have two considerations that may be relevant here:

• If I understand correctly, html-page-context is executed after the end user assets are added in conf.py. This means that the per-page additions to CSS will have a higher priority than those by the end user, and this shouldn't be the case.
• I wonder how an end user would access this behavior? Imagine here a use case where someone writes a documentation of a library that produces rich HTML output. They are unlikely to also want to implement a sphinx extension. Would they be able to hook into the event from conf.py?

[choldgraf]

A quick thought from me:

I wonder how an end user would access this behavior

I think it would be possible with something like:

def add_per_page_css(<html-page-context-args>):
    if pagename in <[list-of-pagenames]>:
        app.add_css_file(<my-css-file>)

def setup(app):
    app.connect("html-page-context", add_per_page_css)

IMO this would be a useful snippet in the documentation somewhere. Maybe somewhere around https://www.sphinx-doc.org/en/master/development/theming.html?highlight=%22add_css_file%22 ?

[akhmerov]

I see, I didn't realize that one can add a setup function to conf.py. The configuration page indeed already mentions:

The configuration file itself can be an extension; for that, you only need to provide a setup() function in it.

So it doesn't need a separate action then.

[tk0miya]

If I understand correctly, html-page-context is executed after the end user assets are added in conf.py. This means that the per-page additions to CSS will have a higher priority than those by the end user, and this shouldn't be the case.

At present, the order of JS/CSS is not mentioned in its specification at all. So it is not defined and not controllable. Please file another issue to control the order if important. For now, I don't have a plan to implement it because I don't know how worth for Sphinx. Of course, I understand it'ss important when building interactive website. But Sphinx is mainly used for the static pages.

[tk0miya]

I wonder how an end user would access this behavior? Imagine here a use case where someone writes a documentation of a library that produces rich HTML output. They are unlikely to also want to implement a sphinx extension. Would they be able to hook into the event from conf.py?

I don't know how many users would like to add JS/CSS conditionally. Additionally, it would be tough to design and implement a new "conditional" configuration. So I'd not like to support conditional JS/CSS via configurations.

IMO, it's not difficult to create a custom event handler in conf.py. So it's easier and simpler to use conditional assets than configurations.

[akhmerov]

Of course, I understand it'ss important when building interactive website. But Sphinx is mainly used for the static pages.

With JS the order probably doesn't matter anyway because it's loaded asynchronously. The order of CSS is however important also in static pages and whenever an extension injects its CSS after user's custom.css, users report an issue (e.g. jupyter/jupyter-sphinx#149 and executablebooks/sphinx-tabs#15). Therefore this matter seems to be within scope of sphinx since it is used for static pages.

At present, the order of JS/CSS is not mentioned in its specification at all. So it is not defined and not controllable.

While the order of CSS is not documented (I'll open an issue about that), it is in practice controllable. The two issues I linked above show that documentation authors do in fact expect being able to override the extension or theme CSS. This PR would remove such ability.

[tk0miya]

Absolutely. I perfectly understand why the order of CSS is important. We have to add a priority feature to CSS API first.

[tk0miya]

Now I posted #8639 to control the order of JS/CSS. It helps that the JS/CSS files registered at the html-page-context event is loaded before user's JS/CSS by default. And extensions can register their JS/CSS files before or after other assets intentionally.

[akhmerov]

Thanks, with #8639 in place, I think everything is perfect.

A question about milestones: this one seems to go into 4.0.0 while #8639 was tagged 3.5.0: is this intentional?

[tk0miya]

Yes. I thought this would be a breaking change. So it would be better to merge this into 4.0. But I'm debating now because it's a very minor change.

[choldgraf]

I think it’d be great if this were in 3.5. I feel like it is a quite “under the hood” change - the “breaking” effect would only affect people who were

• using these methods in the html-page-context event
• and expecting it to apply to all pages instead of one page.

I suspect that this is a pretty small group of people...perhaps we could just log an info statement saying that the behavior has changed or something?

[tk0miya]

Thank you for comment. Finally, I determined to merge this into the 3.x branch.

[humitos]

Is there a way to configure this to behave as it was? I mean, including all the JS and CSS files in all the pages even if they "are not used" in that page?

I'm asking because in my extension sphinx-hoverxref we show a small tooltip with the content of another page from the same documentation. That content could have a math expression that requires MathJax to be render.

Example:

• if you hover on "tooltip with Mathjax" in https://sphinx-hoverxref.readthedocs.io/en/latest/usage.html#tooltip-with-mathjax you will see a tooltip that has a math formula that does not render properly
• if you go to the page where the tooltip brings the content from https://sphinx-hoverxref.readthedocs.io/en/latest/mathjax.html you will see it properly rendered

This is because the page usage.html does not include the mathjax.js with the changes in this PR.

Edit: Note that using Sphinx<3.5 my problem disappears.

[humitos]

I think that I will have the same problem with other 3rd party extensions start using this feature as well. For example in https://sphinx-hoverxref.readthedocs.io/en/latest/usage.html#tooltip-with-sphinx-tabs if you hover "tooltip with Sphinx Tabs" you will see a bigger tooltip that renders tabs ("from PyPI" and "from GitHub") that won't work when sphinx-tabs extension uses this feature to only include their JS files on the "pages that are used".

[tk0miya]

@humitos Could you send a feature request, please? Then I'll consider it later.

[humitos]

Great, thanks! I've created the issue at #9115