Using mathematical equations

LaTeX

The syntax for writing equations is LaTeX. See some examples below.

LaTeX has a steep learning curve, so you may want to check online documentation, for example Overleaf’s LaTeX mathematical expressions guide.

Given that LaTeX syntax may be daunting, a WYSIWYG math editor can be useful, or at least an interactive previewer like latex4technics.

MathJax

In Sphinx, the rendering (display) of the equations can be done in different ways, which won’t be discussed here.

The selected option is to use the sphinx.ext.mathjax extension. This extension uses the JavaScript package MathJax to transform the LaTeX markup to readable math live in the browser.

The mathjax_path in the conf.py file indicates where the MathJax library resides. By default, this is the MathJax site, but the path can be changed if cross-site scripting is NOT allowed.

Math examples

Inline equation

output

If \(\sigma_{1}\) equals \(\sigma_{2}\) then etc, etc.

md

If $\sigma_{1}$ equals $\sigma_{2}$ then etc, etc.

rst

If :math:`\sigma_{1}` equals :math:`\sigma_{2}` then etc, etc.

Inline equation with subscript and superscript

output

\(\underline{x}=[ x_{1}, ..., x_{n}]^{T}\)

md

$\underline{x}=[  x_{1}, ...,  x_{n}]^{T}$

rst

:math:`\underline{x}=[  x_{1}, ...,  x_{n}]^{T}`

Block equation

output

\[ \langle \alpha, \beta \rangle \in \Biggl \lbrace { M,\text{ if } { l(\underline{x}) = \frac { p(\underline{x}|M ) } { p(\underline{x}|U) } \geq \frac { p(U) }{ p(M) } } \atop U, \text{ otherwise } } \]

md

$$
\langle \alpha, \beta  \rangle 
\in 
\Biggl \lbrace 
{ 
M,\text{ if } 
   {
    l(\underline{x}) = 
      \frac { p(\underline{x}|M ) } { p(\underline{x}|U) } 
      \geq
       \frac { p(U) }{ p(M) } }
\atop 
U, \text{ otherwise } 
}
$$

rst

.. math::

   \langle \alpha, \beta  \rangle 
   \in 
   \Biggl \lbrace 
   { 
   M,\text{ if } 
      {
       l(\underline{x}) = 
         \frac { p(\underline{x}|M ) } { p(\underline{x}|U) } 
         \geq
          \frac { p(U) }{ p(M) } }
   \atop 
   U, \text{ otherwise } 
   }

How to label and cross-reference equations

• To add a label to an equation:

output

(1)\[ e^{i\pi} + 1 = 0 \]

md

$$
e^{i\pi} + 1 = 0
$$ (euler-identity)

rst

.. math::
   :label: euler-identity

   e^{i\pi} + 1 = 0

• Once labeled, you can reference the equation anywhere in your documentation using the Sphinx eq role.

output

As shown in equation (1), the relationship between the fundamental mathematical constants is elegant.

md

As shown in equation {eq}`euler-identity`, 
the relationship between the fundamental mathematical constants is elegant.

rst

As shown in equation :eq:`euler-identity`, 
the relationship between the fundamental mathematical constants is elegant.

By default, Sphinx only numbers equations that have a label attached to them. If you want Sphinx to assign a number to every block equation in your documentation (even the ones you haven’t labeled), you can add this line to your conf.py:

math_number_all = True

Warning

Technically, the numbering of equations does not use the same numbering engine as the numbering of tables, figures, and code-blocks.

• For equations, one must use the :label: option / (label-name) and the {eq} role.

• For tables and figures, one must use the :name: option and the {numref} role.

It is how it is…