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