Add support for html_math_renderer = 'mathml'

[jbms]

Fixes #233.

[jbms]

I did a bit of experimentation and was able to get MathML output working fairly easily. However, it could benefit from some CSS styling to fix spacing issues.

This would actually be better suited as a change to Sphinx itself, though.

[2bndy5]

Tagging sphinx-doc/sphinx#6092 for visibility.

[2bndy5]

could benefit from some CSS styling to fix spacing issues

We could probably use the fonts from the npm mathjax dist when #231 gets finalized, but the code points might need translation or metrics might not match up. It might be easier to switch the font caching source to fontsource. I'm not nearly an expert though.

[2bndy5]

Should this be extended to user confval(s)? Does this directly influence the docutils' converter used?

[jbms]

This is basically equivalent to putting:

[html writers]
math_output: mathml

in a docutils.conf file next to the conf.py file.

There is one option that could be specified, an external LaTeX-syntax to MathML converter program to use in place of the one that is built into docutils. Probably there should be a config option for that.

Alternatively this extension could be renamed "docutils_math_renderer" and we could require the user to create the separate docutils.conf file to specify the math format. However, it seems unlikely that a user would want to use any of the docutils math formats other than mathml:

• the mathjax format is already separately supported by sphinx, so I don't think there is any point in supporting that;
• I don't know about the "HTML" format, but if we wanted to support that, we'd have to arrange to include the appropriate math.css stylesheet.

[2bndy5]

I'm really just working with the info from here. I think it would be fine to only use the docutils converter script (latex2mathml). But I was thinking it might be useful if a user already has external converter installed (like pandoc or blahxml) and might want to use that instead.

[jbms]

could benefit from some CSS styling to fix spacing issues

We could probably use the fonts from the npm mathjax dist when #231 gets finalized, but the code points might need translation or metrics might not match up. It might be easier to switch the font caching source to fontsource. I'm not nearly an expert though.

Assuming it is a regular font I expect it will work fine. MathML just encodes math as an element tree but leaves all of the actual layout up to the browser. The MathML converter doesn't know anything about fonts.

I think the choice of font is independent of the issue I had noticed, where using "&" for alignment caused there to be extra space on either side, due to the default padding.

[2bndy5]

I played around a bit with the rendered RTD build... I think the columnspacing can't be adjusted via CSS:

mtable.align {
  columnspacing: 1em;
}

But, setting the columnspacing attr on the element does have a desirable effect. Setting comunmalign="right left" seems to work well also.

Removing the attrs on mtable elements all together seems to use sane defaults (at least for Firefox).

[2bndy5]

It might be worth noting when the escaped line breaks are needed/useful in a doc dedicated to this theme-ext

[2bndy5]

docutils release notes list (under 0.20 changes)

• "html5" writer:
  • Change the default value for math_output to "MathML" in Docutils 0.22.

[jbms]

I added some minimal CSS to try to account for missing attribute support in Chrome. I also copied in the docutils math example doc, and modified it to use rst-example.

I couldn't figure out how to make \mathrm and similar styles work in Chrome with CSS. Firefox supports them by default.

[jbms]

Overall it seems like the MathML support isn't quite ready, though maybe it is adequate for light use.