Sphinx extensions¶

We have described in the previous section the extensions: intersphinx, extlinks, ifconfig, napoleon.

todo extension¶

The extension sphinx.ext.todo allow to include todo blocks like

.. todo::

      We need to achieve:

      .. include:: include/feature.rst

An other directive todolist is replaced by a list of all todo directives in the whole documentation.

These blocks are by default excluded but can be included by setting to True the configuration variable todo_include_todos.

You can either set it in the conf.py file or trigger it by adding the option to sphinx-build. An easy way is through the Make process by doing:

$ make -k html SPHINXOPTS="-D todo_include_todos=1"

Sphinx Math¶

There are three mathematical typesetting Sphinx extensions imgmath, mathjax, and jsmath.

The extension imgmath use LaTeX and dvipng or dvisvgm to render math into PNG or SVG images. You need to install one of these utilities on the machine where the doc is built.

To enable the extension, the following line has to appear in conf.py:

extensions = ['sphinx.ext.imgmath']

You then can type standard LaTeX math expressions, either inline:

:math:`‹LaTeX math expression›`

or in display mode:

.. math::

   ‹LaTeX math expressions›

The second version is also available for a one line expression:

.. math:: ‹1 Line LaTeX math expression›

E.g:

Pythagoras $a^2+b^2=c^2$

$\sum_{n=0}^N x_n = y$

Mathjax and its predecessor jsmath render math through javascript.

Multiline Math¶

Sphinx Built-in Mechanism

Several lines of math expressions can be entered by leaving a blank line between them. In addition there is something like an align environment syntax if lines are not separated by a blank line.

$a+b = c b = x_n a &= y_n\\ &= c-b$

Explicit LaTeX with amsmath mechanism

If the option nowrap is specified then the full LaTeX code (including the math-environment) has to be given. We can assume that the amsmath package is loaded. This is not limited to math typesetting, any LaTeX construct can be rendered in this way.

.. math:: \[a = b\]
   :nowrap:

or equivalenty

.. math::
   :nowrap:

   \[a = b\]

$a = b$

or equivalenty

$a = b$

Equation Numbers¶

Equations are labeled with the label option and referred to using:

:eq:`‹label›`

E.g:

(1)¶ $a^2 + b^2 = c^2$

See equation (1).

Graphs with Graphviz¶

The Graphviz graph drawing Sphinx extension is provided in Sphinx distribution.

To enable the extension we have to add it to the extensions list in conf.py:

extensions = ['sphinx.est.graphviz']

It uses directly the dot command to process DOT language.

Examples¶