diff --git a/HACKING.rst b/HACKING.rst index 42a0a4581dc5..d745a30753b5 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -103,16 +103,18 @@ which will cause a virtualenv with all of the needed dependencies to be created and then inside of the virtualenv, the docs will be created and put into doc/build/html. -If you'd like a PDF of the documentation, you'll need LaTeX installed, and -additionally some fonts. On Ubuntu systems, you can get what you need with:: +Building a PDF of the Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you'd like a PDF of the documentation, you'll need LaTeX and ImageMagick +installed, and additionally some fonts. On Ubuntu systems, you can get what you +need with:: - apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended + apt-get install texlive-full imagemagick -Then run ``build_sphinx_latex``, change to the build dir and run ``make``. -Like so:: +Then you can then use the ``build_latex_pdf.sh`` script in toos/ to take care +of both the the sphinx latex generation and the latex compilation. For example:: - tox -evenv -- python setup.py build_sphinx_latex - cd build/sphinx/latex - make + tools/build_latex_pdf.sh -You should wind up with a PDF - Nova.pdf. +The script must be run from the root of the Nova repository and it'll copy the +output pdf to Nova.pdf in that directory. diff --git a/tools/build_latex_pdf.sh b/tools/build_latex_pdf.sh new file mode 100755 index 000000000000..1d745afd6aa7 --- /dev/null +++ b/tools/build_latex_pdf.sh @@ -0,0 +1,28 @@ +#!/bin/bash + +# Build tox venv and use it +tox -edocs --notest +source .tox/docs/bin/activate + +# Build latex source +sphinx-build -b latex doc/source doc/build/latex + +pushd doc/build/latex + +# Workaround all the sphinx latex bugs + +# Convert svg to png (requires ImageMagick) +convert architecture.svg architecture.png + +# Update the latex to point to the new image, switch unicode chars to latex +# markup, and add packages for symbols +sed -i -e 's/architecture.svg/architecture.png/g' -e 's/\\code{✔}/\\checkmark/g' -e 's/\\code{✖}/\\ding{54}/g' -e 's/\\usepackage{multirow}/\\usepackage{multirow}\n\\usepackage{amsmath,amssymb,latexsym}\n\\usepackage{pifont}/g' Nova.tex + +# To run the actual latex build you need to ensure that you have latex installed +# on ubuntu the texlive-full package will take care of this +make + +deactivate +popd + +cp doc/build/latex/Nova.pdf .