Sphinx LaTeX woes

Posted Oct 27, 2016 11:26 UTC (Thu) by jnareb (subscriber, #46500)
Parent article: A report from the documentation maintainer

> There, getting the documentation built requires executing a seemingly endless loop of
> "which .sty file is missing now, and which package provides it?" work.

Or you can use `texliveonfly` package / tool that implements on demand installation in TeX Live 2010 and later.

> One such issue is the use of the Sphinx math extension, which supports the formatting of mathematical expressions
> using the LaTeX syntax. As of 4.9, the media documentation is using this extension, but there is a cost: it forces
> the use of LaTeX even to build the HTML documentation. The hope is to find an easy way to fall back gracefully
> when LaTeX is unavailable in order to soften this dependency.

Are not there tools that allow conversion of LaTeX math syntax (e.g. $$z^2 = x^2 + y^2$$) to MathML without
requiring LaTeX? There might be a problem with image fallback, but one could use plain text (LaTeX math syntax
or ASCIImath) instead.

Also there are JavaScript-based solutions like MathJax and/or KaTeX, with math rendered client-side.

to post comments

Sphinx LaTeX woes

Posted Oct 27, 2016 16:27 UTC (Thu) by mchehab (subscriber, #41156) [Link]

> Or you can use `texliveonfly` package / tool that implements on demand installation in TeX Live 2010 and later.

Sounds promissing! will do some tests here.

> Are not there tools that allow conversion of LaTeX math syntax (e.g. $$z^2 = x^2 + y^2$$) to MathML without requiring LaTeX? There might be a problem with image fallback, but one could use plain text (LaTeX math syntax or ASCIImath) instead.

There is a MathML extension. We didn't test yet. Not sure what dependencies it would require, nor if it will work for all kinds of document outputs (HTML, ePub and LaTeX/PDF) that the documentation build supports.

> Also there are JavaScript-based solutions like MathJax and/or KaTeX, with math rendered client-side.

The problem is that Spinx accepts just *one* extension to handle math:: tags. So, it should be either sphinx.ext.imgmath or sphinx.ext.mathjax. (http://www.sphinx-doc.org/en/1.4.8/ext/math.html). So, if we move to mathjax, PDF output will likely not work anymore. Maybe with some Python magic we could find a way to make Sphinx conf.py to identify the type of output and switch the extension in runtime. It also seems that the MathJax extension requires an extra package to be installed.

Sphinx LaTeX woes

Posted Oct 27, 2016 21:33 UTC (Thu) by mathstuf (subscriber, #69389) [Link]

There's matplotlib which can render LaTeX and is in Python as well as widely available.