MAINT: switch documentation build from mathjax to imgmath #7358
Conversation
60d3d9a to
2c66f2c
Compare
|
I actually wonder what arxiv/math.SE et al do. (Non-blocking, +1 for the PR itself) |
|
arxiv hosts a copy of mathjax (apparently the full one). This is a bit
different for us, since the scipy documentation should also be readable
offline (it's not currently so).
|
The Mathjax CDN was retired Apr 30 2017, https://www.mathjax.org/cdn-shutting-down/ Mathjax itself is quite big, so rather than bundling it, it probably makes more sense to ship SVG versions of the math formulas instead, using sphinx.ext.imgmath.
|
It's possible to strip mathjax down apparently, so maybe that could be investigated also. |
|
What is the bus factor for fiddling around with JS libs? MathJax looked great while it was a single line in the conf.py, but anything seriously beyond that, and it's not that clear-cut anymore. |
|
They have some sort of (semi-official?) script that prunes out cruft. The problem with imgmath is that png images don't scale, and svg images don't align on the text baseline, so it looks a bit crappy with either output format, whereas mathjax looks nicer. |
|
I'm going to go with the bundled mathjax. |
The Mathjax CDN was retired Apr 30 2017, https://www.mathjax.org/cdn-shutting-down/
I'm not sure if it makes sense for us to rely on 3rd party CDNs for the documentation.
Mathjax itself is quite big, so rather than bundling it, it probably
makes more sense to ship SVG versions of the math formulas instead,
using sphinx.ext.imgmath. This produces 19M of svg images, but that's probably
preferable to the 100+M of mathjax.
This PR doesn't solve the problem that math formulas in previously built docs
will stop displaying properly at some point, but fixing that would need rebuilds.
Fixes gh-7286
circleci: https://circle-artifacts.com/gh/scipy/scipy/2707/artifacts/0/home/ubuntu/scipy/doc/build/html-scipyorg/index.html