openstack/nova
Code Issues Proposed changes

Add tool to build a doc latex pdf

Browse Source 
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
No known key found for this signature in database
GPG Key ID: FD12A0F214C9E177
2 changed files with 39 additions and 9 deletions
Show Stats 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 created and then inside of the virtualenv, the docs will be created and
put into doc/build/html. put into doc/build/html.
If you'd like a PDF of the documentation, you'll need LaTeX installed, and Building a PDF of the Documentation
additionally some fonts. On Ubuntu systems, you can get what you need with:: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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``. Then you can then use the ``build_latex_pdf.sh`` script in toos/ to take care
Like so:: of both the the sphinx latex generation and the latex compilation. For example::
tox -evenv -- python setup.py build_sphinx_latex tools/build_latex_pdf.sh
cd build/sphinx/latex
make
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 .