2015-10-10 A few tips with Sphinx

Sphinx generates many warning when it builds the documentation despite the fact the result looks good. Some cases.

nested bullets

According to How to create a nested list in reStructuredText?, a space must be inserted for nested bullets. The wrong syntax:

* level 1
    * level 2
    * level 2 as well
* level 1 again

The right syntax:

* level 1

    * level 2
    * level 2 as well

* level 1 again

latex formulas

The page Math support in Sphinx explains how to set up math environment (latex or mathjax). But if you add matplotlib to convert equations into images (matplotlib.sphinxext.mathmpl), the sphinx extension sphinx.ext.pngmath is disabled. Matplotlib extension has some limitations. \text does not work.

formulas in docstring

When included in a doc string, backslashes must be doubled:

"""
\\min_i \\{ ...
"""