Sphinx 4.0 Support (including Mathjax 3)

Sphinx 4.0 is now out 🎉 and I’m sure there are some that are anxious to upgrade their documentation to use it.

We also certainly want to allow this. However, there is currently one known blocker for trivially changing the dependency pinning in setup.cfg: sphinx-doc/sphinx#7425 / sphinx-doc/sphinx#9094 (Mathjax 3 support) and its interplay with the “dollarmath”/“amsmath” extension.

In https://myst-parser.readthedocs.io/en/latest/using/syntax.html#mathjax-and-math-parsing, I discuss why we want to override default mathjax configuration; in short because we do not want Mathjax to act as a parser (searching for math, since the Markdown parser already does this), only a renderer (rendering already identified math).

For example, if you set myst_update_mathjax = False, and did not have “dollarmath” nor “amsmath” in myst_enable_extensions, then all of these would still be rendered as math (only with HTML builders but not with other builders like LaTeX)

```{math}
a = 1
```

$$b=2$$

\begin{equation}c=3\end{equation}

or, another example, if you did have “dollarmath” enabled, but myst_update_mathjax = False, then escaped dollar signs would still be rendered as math (again only for HTML builders):

\$\$b=2$$

The way we stop this occuring is to override some of the mathjax extension logic in myst_parser/mathjax.py. But this needs updating for Mathjax 3, plus I also want to revisit the logic and check that this is the best approach.

I should be able to do this by next week though 👍

Cheers, Chris

[chrisjsewell]

us bleeding edge people to use

You damn bleeding edge people 😆 Right I’ll get this done on Monday 👍 while I have some attention, I would ask anyone interested to go comment on: https://github.com/sphinx-doc/sphinx/issues/9040, because my PR there has been waiting to be merged for months, so its a similar frustration lol

[cooperlees]

Hi all - What’s the expected time frame on removing the version pinning? What are the main blockers to support sphinx >= 4.0.0? It seems only $$ right?

What are our options here? As someone who does not use $$ can we offer a pre version maybe that’s unpinned while this is worked out for us bleeding edge people to use?