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
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.
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\]
|
or equivalenty |
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.