Get website documentation to display math

[guyer]

Fixes #762

[guyer]

Try as I might, I couldn't get sphinx.ext.mathjax working satisfactorily. The math renders fine, but MathJax is pointedly not TeX, and definitely not LaTeX. We import some packages and define some commands in conf.py and I couldn't make enough of it work:

• The SIunits package is archaic. There's an siunitsx proxy for MathJax 2.x, but it's buggy, and it's really clunky to load it in sphinx.
• changepage is for the PDF rendering, not web
• defining \abs is OK
• Making \erf a math operator stymies me. MathJax 3.x has a physics package that includes \abs and \erf, but for the life of me I can't get it to load. MathJax 3.x also broke my def of \abs.

I'm fed up and am giving up. SVG is good enough.

Sphinx 4.x apparently migrated to MathJax 3.x. At such point as conda-forge starts supplying Sphinx 4.x, it may be worth revisiting this.

[tkphd]

Can we cheat using \mathrm{erf}?

[guyer]

Can we cheat using \mathrm{erf}?

mayhaps

[tkphd]

Changes appear straightforward; docs build locally and look fine (i.e., equations are present & accounted for). MathJax support would be a good follow-up issue.

[wd15]

I'm not seeing the equations locally. What am I doing wrong?

Edit: I didn't have a working latex in the environment

[wd15]

Works for me. Could we set it to fail if latex doesn't run from some reason?

[guyer]

Could we set it to fail if latex doesn't run from some reason?

I don't know, but it would be desirable. That was why I missed that it didn't build right on CircleCI.

[guyer]

Could we set it to fail if latex doesn't run from some reason?

imgmath logs and raises an error when it can't find a LaTeX component it needs, but then it discards the error.

It seems like the CI command needs to grep for ".* command '.*' cannot be run \(needed for math display\), check the imgmath_.* setting" and exit non-zero, but doing that, while still outputting the log is beyond my shelling.

Something, something, tee?

[wd15]

Could we set it to fail if latex doesn't run from some reason?

imgmath logs and raises an error when it can't find a LaTeX component it needs, but then it discards the error.

It seems like the CI command needs to grep for ".* command '.*' cannot be run \(needed for math display\), check the imgmath_.* setting" and exit non-zero, but doing that, while still outputting the log is beyond my shelling.

Something, something, tee?

Thanks for looking into it. I would say that it's probably better to get sphinx to return in a failed state rather than having the CI try to interpret the output.