Browse Source

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

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:
https://governance.openstack.org/tc/goals/train/pdf-doc-generation.html
https://etherpad.openstack.org/p/train-pdf-support-goal
https://etherpad.openstack.org/p/pdf-goal-train-common-problems

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>
changes/48/681448/5
Bogdan Dobrelya 2 years ago
parent
commit
dd02f75d56
6 changed files with 45 additions and 36 deletions
  1. +4
    -9
      CONTRIBUTING.rst
  2. +11
    -11
      README.rst
  3. +4
    -3
      doc/requirements.txt
  4. +7
    -3
      doc/source/conf.py
  5. +8
    -10
      doc/source/index.rst
  6. +11
    -0
      tox.ini

+ 4
- 9
CONTRIBUTING.rst 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:
https://wiki.openstack.org/wiki/How_To_Contribute
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:
https://docs.openstack.org/infra/manual/developers.html
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:
https://bugs.launchpad.net/tripleo
Bugs should be filed on `TripleO at Launchpad <https://bugs.launchpad.net/tripleo>`_
not GitHub.

+ 11
- 11
README.rst View File

@ -1,15 +1,9 @@
========================
Team and repository tags
========================
.. 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
===================
About tripleoclient
===================
=============
tripleoclient
=============
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

+ 4
- 3
doc/requirements.txt 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

+ 7
- 3
doc/source/conf.py View File

@ -23,8 +23,12 @@ extensions = [
'sphinx.ext.autodoc',
'openstackdocstheme',
'cliff.sphinxext',
'sphinxcontrib.rsvgconverter',
]
# 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 = [
('index',
'tripleoclient.tex',
u'tripleoclient Documentation',
'doc-python-tripleoclient.tex',
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'


+ 8
- 10
doc/source/index.rst View File

@ -1,22 +1,20 @@
=============
tripleoclient
Tripleoclient
=============
tripleoclient is an OpenStackClient plugin.
Contents:
.. toctree::
:maxdepth: 2
readme
contributing
installation
usage
commands
contributing
Indices and tables
==================
.. only:: html
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
* :ref:`genindex`
* :ref:`search`

+ 11
- 0
tox.ini View File

@ -72,6 +72,17 @@ show-source = True
builtins = _
exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build,releasenotes
[testenv:pdf-docs]
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
[testenv:genconfig]
basepython = python3
setenv =


Loading…
Cancel
Save