question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Sphinx 4.0 Support (including Mathjax 3)

See original GitHub issue

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

Issue Analytics

  • State:closed
  • Created 2 years ago
  • Reactions:7
  • Comments:13 (7 by maintainers)

github_iconTop GitHub Comments

6reactions
chrisjsewellcommented, Jun 3, 2021

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

2reactions
cooperleescommented, Jun 2, 2021

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?

Read more comments on GitHub >

github_iconTop Results From Across the Web

Math support for HTML outputs in Sphinx
Since mathematical notation isn't natively supported by HTML in any way, Sphinx gives a math support to HTML document with several extensions.
Read more >
Configuring MathJax in Sphinx documentation - Stack Overflow
I am using restructured text and Sphinx to create content for a class. The content is hosted on readthedocs (an example is here)....
Read more >
sphinxcontrib-katex - PyPI
A Sphinx extension for rendering math in HTML pages. The extension uses KaTeX for rendering of math in HTML pages. It is designed...
Read more >
What's New in MathJax v3.2
Lazy Typesetting¶. Although MathJax version 3 is already an order of magnitude faster than version 2, with version 3.2 we offer a new...
Read more >
MathJax Documentation - Read the Docs
3 Installing and Testing MathJax. 13. 4 Loading and Configuring MathJax. 19. 5 Combined Configurations. 27. 6 MathJax TeX and LaTeX Support.
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found