DOC: switch to KaTeX for math rendering

[hagenw]

This is an alternative to #80.
LaTeX definitions can be easier integrated by using KaTeX instead of mathjax.

This avoids including the LaTeX definitions several times as they are just passed once to the LaTeX preamble.

[hagenw]

This is a little bit ugly, but we could also do the latex_macros definition directly in conf.py.

[mgeier]

Thanks!

AFAIK, KaTeX still doesn't support environments like \begin{equation}...\end{equation}, right?

As long as that's not the case, I'm hesitating to switch.

LaTeX definitions can be easier integrated by using KaTeX instead of mathjax.

I don't think that's true.

It's also possible in MathJax: https://docs.mathjax.org/en/latest/tex.html#defining-tex-macros

We would just have to write some conversion code like you did in https://github.com/hagenw/sphinxcontrib-katex/blob/52e235b93a2471df9a7477e04b697e4274399623/sphinxcontrib/katex.py#L32-L68.

I've just create #82 for yet another alternative.

[hagenw]

That's correct, \begin{equation}...\end{equation} isn't supported, see KaTeX/KaTeX#445.
Here is a list of the supported environments: https://katex.org/docs/supported.html#environments

I never needed the equation environment with rst so far, but I guess it might be of interest for Jupyter notebooks? If it should be just interpreted as a math limiter it could easily been added to delimiters as proposed in the issue, but it will not add numbers to the equations then.

But it's totally fine with me if we go with #82 for now.

[mgeier]

I guess it might be of interest for Jupyter notebooks?

Exactly.
But I'm actually not sure if we will ever need this in our example notebooks.

I've created yet another alternatve: #90.

I do like the explicit use of

.. include:: math-definitions.rst

I think defining the stuff in conf.py is a bit less obvious and a bit harder to follow.

And if my PR jupyterlab/jupyterlab#5997 is accepted, a similar method will be available for Jupyter notebooks.

My PR #90 doesn't preclude switching to KaTeX at some point, because AFAIK \gdefis supported out-of-the-box in KaTeX.

[mgeier]

I've merged #90 which solves the original problem.

We can still discuss switching to KaTeX at some point in the future.
But since there are still some missing features, I'm currently skeptical about the switch.

[hagenw]

Yes, don't worry, there is no urgent need.