sphinx / doc / ext / math.rst

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:

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.