problem rendering math

[wikfeldt]

hey!
I'm trying to fix this math-rendering problem for jupyter notebooks as source for lesson episodes. See the latex code under https://enccs.github.io/NordIQuEst-workshop/E1_qc-1/#quantum-circuits for an example of the problem.

When building locally, math renders correctly with an old messy conda environment that's been updated once in a while. This working environment has the following packages:

$ conda list | grep 'myst\|sphinx\|jupyter'

jupyter-cache             0.4.3                    pypi_0    pypi
jupyter-client            7.1.2                    pypi_0    pypi
jupyter-core              4.9.2                    pypi_0    pypi
jupyter-server            1.13.5                   pypi_0    pypi
jupyter-server-mathjax    0.2.5                    pypi_0    pypi
jupyter-sphinx            0.3.2                    pypi_0    pypi
jupyterlab-pygments       0.1.2                    pypi_0    pypi
jupyterlab-widgets        1.0.2                    pypi_0    pypi
myst-nb                   0.13.2                   pypi_0    pypi
myst-parser               0.15.2                   pypi_0    pypi
pydata-sphinx-theme       0.8.1                    pypi_0    pypi
sphinx                    4.4.0                    pypi_0    pypi
sphinx-autobuild          2021.3.14                pypi_0    pypi
sphinx-book-theme         0.3.2                    pypi_0    pypi
sphinx-coderefinery-branding 0.1.0                    pypi_0    pypi
sphinx-copybutton         0.5.0                    pypi_0    pypi
sphinx-lesson             0.8.10                   pypi_0    pypi
sphinx-minipres           0.2.1                    pypi_0    pypi
sphinx-rtd-theme          1.0.0                    pypi_0    pypi
sphinx-rtd-theme-ext-color-contrast 0.3.0                    pypi_0    pypi
sphinx-tabs               3.3.1                    pypi_0    pypi
sphinx-thebe              0.1.2                    pypi_0    pypi
sphinx-togglebutton       0.3.0                    pypi_0    pypi
sphinxcontrib-applehelp   1.0.2                    pypi_0    pypi
sphinxcontrib-bibtex      2.4.2                    pypi_0    pypi
sphinxcontrib-devhelp     1.0.2                    pypi_0    pypi
sphinxcontrib-htmlhelp    2.0.0                    pypi_0    pypi
sphinxcontrib-jsmath      1.0.1                    pypi_0    pypi
sphinxcontrib-qthelp      1.0.3                    pypi_0    pypi
sphinxcontrib-serializinghtml 1.1.5                    pypi_0    pypi

A new local environment with the dependencies i thought were sufficient does not work however. This non-working env has this:

$ conda list | grep 'myst\|sphinx\|jupyter'

jupyter-cache             0.5.0                    pypi_0    pypi
jupyter-client            7.3.1                    pypi_0    pypi
jupyter-core              4.10.0                   pypi_0    pypi
jupyter-server            1.17.0                   pypi_0    pypi
jupyter-server-mathjax    0.2.5                    pypi_0    pypi
jupyter-sphinx            0.3.2                    pypi_0    pypi
jupyterlab-pygments       0.2.2                    pypi_0    pypi
jupyterlab-widgets        1.1.0                    pypi_0    pypi
myst-nb                   0.15.0                   pypi_0    pypi
myst-parser               0.17.2                   pypi_0    pypi
sphinx                    4.5.0                    pypi_0    pypi
sphinx-autobuild          2021.3.14                pypi_0    pypi
sphinx-copybutton         0.5.0                    pypi_0    pypi
sphinx-lesson             0.8.12                   pypi_0    pypi
sphinx-minipres           0.2.1                    pypi_0    pypi
sphinx-rtd-theme          1.0.0                    pypi_0    pypi
sphinx-rtd-theme-ext-color-contrast 0.3.0                    pypi_0    pypi
sphinx-tabs               3.3.1                    pypi_0    pypi
sphinx-togglebutton       0.3.1                    pypi_0    pypi
sphinxcontrib-applehelp   1.0.2                    pypi_0    pypi
sphinxcontrib-devhelp     1.0.2                    pypi_0    pypi
sphinxcontrib-htmlhelp    2.0.0                    pypi_0    pypi
sphinxcontrib-jsmath      1.0.1                    pypi_0    pypi
sphinxcontrib-qthelp      1.0.3                    pypi_0    pypi
sphinxcontrib-serializinghtml 1.1.5                    pypi_0    pypi

Any ideas what's missing?

[wikfeldt]

so, the problem is specifically with $ syntax. The following does not render correctly with the gh-action:

$$
\ket{\psi_I} = \ket{0} \otimes \ket{0} \otimes \ket{0} \otimes \ket{0} \equiv
\ket{0000}.
$$

but this works:

```{math}
\ket{\psi_I} = \ket{0} \otimes \ket{0} \otimes \ket{0} \otimes \ket{0} \equiv
\ket{0000}.
```

I want the former to work because then learners can use the actual notebooks for the episodes for exercises, with nice rendered math etc. any pointers @rkdarst ?

[rkdarst]

Hm, somehow this makes me think it is an issue with the parser, in this case myst-nb or myst-parser. the docutils(~=ReST) semantics only handle directives/roles with math, but not $ natively.

This looks relevant:
executablebooks/MyST-Parser#505 (explains some reasoning)

Solution is likely dollarmath to extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#math-shortcuts

myst_enable_extensions = ["dollarmath", "amsmath", "myst_dmath_double_inline"]

... well, look at those extensions and see what you need.

[wikfeldt]

thanks Richard! It now works with

myst_enable_extensions = ["dollarmath","amsmath"]

myst_dmath_double_inline is apparently not supported in myst-nb 0.15.0