Source

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.

Note

:mod:`sphinx.ext.mathbase` does not need to be added to the :confval:`extensions` config value.

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.jsmath` -- Render math via JavaScript

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

Because jsMath (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: