sphinx / doc / ext / math.rst

Full commit

Math support in Sphinx

Since mathematical notation isn't natively supported by HTML in any way, Sphinx supports math in documentation with two extensions.

The basic math support that is common to both extensions is contained in :mod:`sphinx.ext.mathbase`. Other math support extensions should, if possible, reuse that support too.


:mod:`.mathbase` is not meant to be added to the :confval:`extensions` config value, instead, use either :mod:`sphinx.ext.pngmath` or :mod:`sphinx.ext.jsmath` as described below.

The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output.

:mod:`.mathbase` defines these new markup elements:

:mod:`sphinx.ext.pngmath` -- Render math as PNG images

This extension renders math via LaTeX and dvipng into PNG images. This of course means that the computer where the docs are built must have both programs available.

There are various config values you can set to influence how the images are built:

:mod:`sphinx.ext.mathjax` -- Render math via JavaScript

This extension puts math as-is into the HTML files. The JavaScript package MathJax is then loaded and transforms the LaTeX markup to readable math live in the browser.

Because MathJax (and the necessary fonts) is very large, it is not included in Sphinx. You must install it yourself, and give Sphinx its path in this config value:

:mod:`sphinx.ext.jsmath` -- Render math via JavaScript

This extension works just as the MathJax extension does, but uses the older package jsMath. It provides this config value: