Add mathjax3_config config option

[mgeier]

This is a draft for an alternative to #8940 and #8971, and it might eventually close #8195 (or not!).

The limitation (for me) is that this still doesn't solve my problem mentioned in #8195 (comment).

Let me describe the problem in more detail:

In nbsphinx I would like to provide default values for both mathjax2_config and mathjax3_config, in order for users to be free to choose whichever version they want with mathjax_path and always get my defaults.

If I provide defaults for both mathjax2_config and mathjax3_config, the current logic in this PR will not raise a warning.
This may sound OK, but if a user previously (and correctly) used mathjax_config, their custom config will stop working and there will be no warning!

I could instead only provide a default in nbsphinx for mathjax3_config (and leave mathjax2_config/mathjax_config untouched), but this wouldn't help in the previous case where a user uses mathjax_config, because the warning would still not be shown.

Any ideas how to make this work?

Feature or Bugfix

Something in-between.

Purpose

Provide a way to specify MathJax v3 settings.

Details

If both mathjax2_config and mathjax3_config are given, both configurations will be written to the HTML output.

[tk0miya]

I also don't have a magical bullet for this problem. But I think this would help for Sphinx users who have their own mathjax_config for v2. So I'd like to merge this to Sphinx-4.0. What do you think?

[mgeier]

It's not perfect, but I think we can use this!

Thanks to the new explicit config names mathjax2_config and mathjax3_config, I was able to make this work with nbsphinx, see spatialaudio/nbsphinx#558.
In this, I'm only providing default values for one of the MathJax versions and there is only one very little edge case where my default values get lost, but I can live with that.

[mgeier]

@tk0miya Should I add a type and subtype for the warning? If yes, which one?

If you decide to merge this, I can add some documentation (either here or in a separate PR).

[tk0miya]

To suppress the warning is meaningless to me. If my understanding correct, the math configuration would not work when the warning is shown. Users should update their configuration instead of suppressing. So it's not needed.

If you decide to merge this, I can add some documentation (either here or in a separate PR).

I'll merge this after a while (maybe 3-4 hours later). If you have time until then, please add a document and CHANGES entry. It's helpful to me.

[mgeier]

OK, I'm on it ...

[mgeier]

OK, done, I've added some docs: https://sphinx--9094.org.readthedocs.build/en/9094/usage/extensions/math.html#confval-mathjax3_config

I didn't know a good example value for mathjax3_config. I you know one, please let me know or feel free to add it yourself.

[tk0miya]

Thank you for your update! Merging now.

[tk0miya]

Oops. I wrongly merged this into the 4.x branch. I'll cherry-pick this into the 4.0.x branch manually.

[mgeier]

Thanks @tk0miya!

[choldgraf]

This looks great, thanks very much @mgeier - many will benefit from this!