PDF documentation build

The is one of community goals that each project could produce a
single PDF file. The pdf should be in the output of openstack-tox-docs

The list of changes:
- add a new pdf-docs environment to enable PDF build,
- sphinxcontrib-svg2pdfconverter is used to handle SVG properly,
- poke versions for sphinx and openstackdocstheme,
- disable usage of xindy for tex,
- do not generate empty pages,
- only build html for toctree and other content-less for pdf sections,
- adjust README to firstly contain "About tripleo" then team & repo tags
  for the better view in PDF-generated contents.
- move the Contributing chapter closer to the beginning for the better
  view in the long list of generated contents.

More about the goal:

TeX and  few more packages may be needed to build PDF locally
(listed for bindep):

inkscape [doc platform:dpkg]
fonts-liberation [doc platform:dpkg]
texlive-latex-base [doc platform:dpkg]
texlive-latex-extra [doc platform:dpkg]
texlive-xetex [doc platform:dpkg]
texlive-fonts-recommended [doc platform:dpkg]
xindy [doc platform:dpkg]
latexmk [doc platform:dpkg]
texlive [doc platform:rpm]
texlive-fncychap [doc platform:rpm]
texlive-titlesec [doc platform:rpm]
texlive-tabulary [doc platform:rpm]
texlive-framed [doc platform:rpm]
texlive-wrapfig [doc platform:rpm]
texlive-upquote [doc platform:rpm]
texlive-capt-of [doc platform:rpm]
texlive-needspace [doc platform:rpm]
texlive-polyglossia [doc platform:rpm]
latexmk [doc platform:rpm]
python3-sphinxcontrib-svg2pdfconverter-common [doc platform:rpm]
librsvg2-tools [doc platform:rpm]
librsvg2-bin [doc platform:dpkg]

Change-Id: Ib3bb34191582f581c28f2f8a0281cf3ae44003e8
Signed-off-by: Bogdan Dobrelya <bdobreli@redhat.com>
Bogdan Dobrelya 2019-08-16 00:52:14 +09:00
parent 531f36e4b4
commit dd02f75d56
6 changed files with 45 additions and 36 deletions

View File

@ -1,17 +1,12 @@
If you would like to contribute to the development of OpenStack,
you must follow the steps in the "If you're a developer, start here"
section of this page:
section of `How To Contribute Guide <https://wiki.openstack.org/wiki/How_To_Contribute>`_.
Once those steps have been completed, changes to OpenStack
should be submitted for review via the Gerrit tool, following
the workflow documented at:
the documented `Development Workflow <https://docs.openstack.org/infra/manual/developers.html>`_.
Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
Bugs should be filed on `TripleO at Launchpad <https://bugs.launchpad.net/tripleo>`_
not GitHub.

View File

@ -1,15 +1,9 @@
Team and repository tags
About tripleoclient
.. image:: https://governance.openstack.org/tc/badges/python-tripleoclient.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
.. Change things from this point on
General information
**tripleoclient** is an OpenStackClient (OSC) plugin implementation that
implements commands useful for TripleO and the install and management of
@ -21,3 +15,9 @@ for details on using tripleoclient.
See the
`Release Notes <https://docs.openstack.org/releasenotes/python-tripleoclient>`_
Team and repository tags
.. image:: https://governance.openstack.org/tc/badges/python-tripleoclient.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html

View File

@ -1,7 +1,8 @@
# The order of packages is significant, because pip processes them in the order
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
sphinx>=1.6.2,!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7' # BSD
sphinx>=1.6.2,!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4' # BSD
openstackdocstheme>=1.20.0 # Apache-2.0
sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
openstackdocstheme>=1.30.0 # Apache-2.0
reno>=2.5.0 # Apache-2.0

View File

@ -23,8 +23,12 @@ extensions = [
# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
latex_use_xindy = False
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
@ -66,13 +70,13 @@ htmlhelp_basename = 'tripleoclientdoc'
# [howto/manual]).
latex_documents = [
u'tripleoclient Documentation',
u'Tripleoclient Documentation',
u'OpenStack Foundation', 'manual'),
# Allow deeper levels of nesting for \begin...\end stanzas
latex_elements = {'maxlistdepth': 10}
latex_elements = {'maxlistdepth': 10, 'extraclassoptions': ',openany,oneside'}
# openstackdocstheme options
repository_name = 'openstack/python-tripleoclient'

View File

@ -1,22 +1,20 @@
tripleoclient is an OpenStackClient plugin.
.. toctree::
:maxdepth: 2
Indices and tables
.. only:: html
* :ref:`genindex`
* :ref:`search`
Indices and tables
* :ref:`genindex`
* :ref:`search`

View File

@ -72,6 +72,17 @@ show-source = True
builtins = _
basepython = python3
whitelist_externals = make
description =
Build PDF documentation.
envdir = {toxworkdir}/docs
deps = {[testenv:docs]deps}
commands =
sphinx-build -b latex doc/source doc/build/pdf
make -C doc/build/pdf
basepython = python3
setenv =