latex - 1/1 Blog automation (4) documentation (8) example (2) latex (2) notebook (4) sphinx (10)
latex - 1/1¶
A few tips with Sphinx¶
2015-10-10
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 \\{ ...
"""
Conversion to latex is taking for ever¶
2015-04-16
The unit tests are now scheduled using Jenkins. When the documentation is generated for the first time after a fresh installation of the machine (latex, sphinx...), the compilation can take for ever. This is due to extra packages needed by latex. When the process is run from a command line, a windows shows up asking for approval before going on installing the missing latex packages. As this command line is showing up in the output, it is just needed to executed from a command line window to import the missing package. After this short break, the latex compilation runs fine on Jenkins.
latex - 1/1 2015-04 (8) 2015-05 (4) 2015-08 (2) 2015-10 (1) 2015-12 (3) 2016-01 (1) 2016-02 (3) 2016-04 (1) 2016-06 (1)