Add tool to build a doc latex pdf

Code Issues Proposed changes

The sphinx latex generation generates invalid latex that won't compile
when you try to use it.[1][2] This commit adds a helper script to generate
the sphinx latex and then modify it so it'll work. It depends on
ImageMagick convert and sed being available to work.
[1] https://github.com/sphinx-doc/sphinx/issues/1907
[2] https://github.com/sphinx-doc/sphinx/issues/1959
Change-Id: Id289c10907aaddae2483f18b39063852ec699d66

This commit is contained in:

Matthew Treinish

2015年07月07日 18:32:59 -04:00

parent 42d91ebee0

commit 62575dd40e

2 changed files with 39 additions and 9 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download Patch File Download Diff File Expand all files Collapse all files

20
HACKING.rst

View File

@@ -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.

28
tools/build_latex_pdf.sh Executable file

View File

@@ -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 .