Math support in Sphinx — flask-peewee v0.1.0 documentation

### Navigation

- index
- modules |
- flask-peewee v0.1.0 documentation »

# 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 two extensions.

The basic math support that is common to both extensions 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 :confval:`extensions` config value, instead, use either `sphinx.ext.pngmath` or `sphinx.ext.jsmath` 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.

`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 a label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. See `eqref` 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 cross-referencing equations via their label. This currently works only within the same document. 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.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:

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

### Navigation

- index
- modules |
- flask-peewee v0.1.0 documentation »