Sphinx extensions¶
We have described in the previous section the extensions: autosectionlabel, intersphinx, extlinks, ifconfig, napoleon.
There are part of Sphinx builtin extensions, a collection of third-party Sphinx extensions is in sphinx-contrib repository.
Awesome Sphinx has also a list of extensions, and sphinx documentation has extension tutorials and a Developing extensions for Sphinx chapter.
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"
Math Extensions.¶
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']
Mathjax and its predecessor jsmath render math through javascript.
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.