Buildhosts¶

To get best results from build, its recommend to install additional packages on build hosts.

Build docs¶

Most of the sphinx requirements are installed from git://setup.py and the docs can be build from scratch with make docs. For better math and image processing additional packages are needed. The XeTeX needed not only for PDF creation, its also needed for Math equations when HTML output is build.

To be able to do Math support for HTML outputs in Sphinx without CDNs, the math are rendered as images (sphinx.ext.imgmath extension). If your docs build (make docs) shows warnings like this:

WARNING: dot(1) not found, for better output quality install \
         graphviz from http://www.graphviz.org
..
WARNING: LaTeX command 'latex' cannot be run (needed for math \
         display), check the imgmath_latex setting

you need to install additional packages on your build host, to get better HTML output.

$ sudo apt install graphviz imagemagick texlive-xetex librsvg2-bin

$ sudo pacman -S graphviz imagemagick texlive-bin extra/librsvg

$ sudo dnf install graphviz graphviz-gd texlive-xetex-bin librsvg2-tools

For PDF output you also need:

$ sudo apt texlive-latex-recommended texlive-extra-utils ttf-dejavu

$ sudo pacman -S texlive-core texlive-latexextra ttf-dejavu

$ sudo dnf install \
       texlive-collection-fontsrecommended texlive-collection-latex \
       dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fonts

html_math_renderer = 'imgmath'
imgmath_image_format = 'svg'
imgmath_font_size = 14