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 several extensions.

The basic math support 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.mathjax` 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.

Keep in mind that when you put math markup in Python docstrings read by :mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes, or use Python raw strings (r"raw").

: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.

: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: