sphinx-doc/sphinx

Extend `sphinx.ext.mathjax` to support static output

Open

#8453 aperta il 20 nov 2020

Vedi su GitHub
 (1 commento) (4 reazioni) (0 assegnatari)Python (1985 fork)batch import
extensions:mathematicshelp wantedmarkuptype:enhancement

Metriche repository

Star
 (5625 star)
Metriche merge PR
 (Merge medio 10g 11h) (11 PR mergiate in 30 g)

Descrizione

Mathjax is normally processed client-side (dynamically rendered with javascript), but with CommonHTML it is now also possible to process it server-side. From the official MathJax documentation:

The CommonHTML output processor renders your mathematics using HTML with CSS styling. Its major advantage is its quality, consistency, and the fact that its output is independent of the browser, operating system, and user environment. This means you can pre-process mathematics on a server, without needing to know the browser, what fonts are available, and so on.

Rather than implementing server-side postprocessing of the output generated by Sphinx, however, I would much rather have that sphinx.ext.mathjax was extended to support output that needed no additional processing. That is, I would like Sphinx to be able to generate offline readable static documents containing mathematics, without resorting to images (i.e., sphinx.ext.imgmath). I believe this can be done by letting sphinx.ext.mathjax open a connection to the mathjax server specified in the mathjax_path option already available, and replace the sphinx nodes by CommonHTML output one by one. The documentation of this feature should include a kind warning that this mathjax feature only supports modern browsers (currently backported to IE 8).

Guida contributor