Math support in Sphinx¶
New in version 0.5.
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 sphinx.ext.mathbase
. Other math
support extensions should, if possible, reuse that support too.
Note
mathbase
is not meant to be added to the extensions
config
value, instead, use either sphinx.ext.imgmath
or
sphinx.ext.mathjax
as described below.
The input language for mathematics is LaTeX markup. This is the defacto standard for plaintext 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
autodoc
, you either have to double all backslashes,
or use Python raw strings (r"raw"
).
mathbase
provides the following config values:

math_number_all
¶ Set this option to
True
if you want all displayed math to be numbered. The default isFalse
.

math_eqref_format
¶ A string that are used for format of label of references to equations. As a special character,
{number}
will be replaced to equaition number.Example:
'Eq.{number}'
is rendered asEq.10

math_numfig
¶ If
True
, displayed math equations are numbered across pages whennumfig
is enabled. Thenumfig_secnum_depth
setting is respected. Theeq
, notnumref
, role must be used to reference equation numbers. Default isTrue
.New in version 1.7.
mathbase
defines these new markup elements:

:math:
¶ Role for inline math. Use like this:
Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

.. math::
¶ Directive for displayed math (math that takes the whole line for itself).
The directive supports multiple equations, which should be separated by a blank line:
.. math:: (a + b)^2 = a^2 + 2ab + b^2 (a  b)^2 = a^2  2ab + b^2
In addition, each single equation is set within a
split
environment, which means that you can have multiple aligned lines in an equation, aligned at&
and separated by\\
:.. math:: (a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2
For more details, look into the documentation of the AmSMath LaTeX package.
When the math is only one line of text, it can also be given as a directive argument:
.. math:: (a + b)^2 = a^2 + 2ab + b^2
Normally, equations are not numbered. If you want your equation to get a number, use the
label
option. When given, it selects an internal label for the equation, by which it can be crossreferenced, and causes an equation number to be issued. Seeeq
for an example. The numbering style depends on the output format.There is also an option
nowrap
that prevents any wrapping of the given math in a math environment. When you give this option, you must make sure yourself that the math is properly set up. For example:.. math:: :nowrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}

:eq:
¶ Role for crossreferencing equations via their label. Example:
.. math:: e^{i\pi} + 1 = 0 :label: euler Euler's identity, equation :eq:`euler`, was elected one of the most beautiful mathematical formulas.
sphinx.ext.imgmath
– Render math as images¶
New in version 1.4.
This extension renders math via LaTeX and dvipng or dvisvgm into PNG or SVG 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:

imgmath_image_format
¶ The output image format. The default is
'png'
. It should be either'png'
or'svg'
.

imgmath_latex
¶ The command name with which to invoke LaTeX. The default is
'latex'
; you may need to set this to a full path iflatex
is not in the executable search path.Since this setting is not portable from system to system, it is normally not useful to set it in
conf.py
; rather, giving it on the sphinxbuild command line via theD
option should be preferable, like this:sphinxbuild b html D imgmath_latex=C:\tex\latex.exe . _build/html
This value should only contain the path to the latex executable, not further arguments; use
imgmath_latex_args
for that purpose.

imgmath_dvipng
¶ The command name with which to invoke
dvipng
. The default is'dvipng'
; you may need to set this to a full path ifdvipng
is not in the executable search path. This option is only used whenimgmath_image_format
is set to'png'
.

imgmath_dvisvgm
¶ The command name with which to invoke
dvisvgm
. The default is'dvisvgm'
; you may need to set this to a full path ifdvisvgm
is not in the executable search path. This option is only used whenimgmath_image_format
is'svg'
.

imgmath_latex_args
¶ Additional arguments to give to latex, as a list. The default is an empty list.

imgmath_latex_preamble
¶ Additional LaTeX code to put into the preamble of the short LaTeX files that are used to translate the math snippets. This is empty by default. Use it e.g. to add more packages whose commands you want to use in the math.

imgmath_dvipng_args
¶ Additional arguments to give to dvipng, as a list. The default value is
['gamma', '1.5', 'D', '110', 'bg', 'Transparent']
which makes the image a bit darker and larger then it is by default, and produces PNGs with a transparent background. This option is used only whenimgmath_image_format
is'png'
.

imgmath_dvisvgm_args
¶ Additional arguments to give to dvisvgm, as a list. The default value is
['nofonts']
. This option is used only whenimgmath_image_format
is'svg'
.

imgmath_use_preview
¶ dvipng
has the ability to determine the “depth” of the rendered text: for example, when typesetting a fraction inline, the baseline of surrounding text should not be flush with the bottom of the image, rather the image should extend a bit below the baseline. This is what TeX calls “depth”. When this is enabled, the images put into the HTML document will get averticalalign
style that correctly aligns the baselines.Unfortunately, this only works when the previewlatex package is installed. Therefore, the default for this option is
False
.Currently this option is only used when
imgmath_image_format
is'png'
.

imgmath_add_tooltips
¶ Default:
True
. If false, do not add the LaTeX code as an “alt” attribute for math images.

imgmath_font_size
¶ The font size (in
pt
) of the displayed math. The default value is12
. It must be a positive integer.
sphinx.ext.mathjax
– Render math via JavaScript¶
New in version 1.1.
This extension puts math asis 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.

mathjax_path
¶ The path to the JavaScript file to include in the HTML files in order to load MathJax.
The default is the
https://
URL that loads the JS files from the cdnjs Content Delivery Network. See the MathJax Getting Started page for details. If you want MathJax to be available offline, you have to download it and set this value to a different path.The path can be absolute or relative; if it is relative, it is relative to the
_static
directory of the built docs.For example, if you put MathJax into the static path of the Sphinx docs, this value would be
MathJax/MathJax.js
. If you host more than one Sphinx documentation set on one server, it is advisable to install MathJax in a shared location.You can also give a full
https://
URL different from the CDN URL.
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:

jsmath_path
¶ The path to the JavaScript file to include in the HTML files in order to load JSMath. There is no default.
The path can be absolute or relative; if it is relative, it is relative to the
_static
directory of the built docs.For example, if you put JSMath into the static path of the Sphinx docs, this value would be
jsMath/easy/load.js
. If you host more than one Sphinx documentation set on one server, it is advisable to install jsMath in a shared location.