From dd02f75d56da25c3f69e92354a0a183c8438793e Mon Sep 17 00:00:00 2001 From: Bogdan Dobrelya Date: Fri, 16 Aug 2019 00:52:14 +0900 Subject: [PATCH] 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 --- CONTRIBUTING.rst | 13 ++++--------- README.rst | 22 +++++++++++----------- doc/requirements.txt | 7 ++++--- doc/source/conf.py | 10 +++++++--- doc/source/index.rst | 18 ++++++++---------- tox.ini | 11 +++++++++++ 6 files changed, 45 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index e9add5bf8..f8a60d601 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 `_. 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 `_. 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 `_ +not GitHub. diff --git a/README.rst b/README.rst index d9de986e6..4e5f7e7ce 100644 --- a/README.rst +++ b/README.rst @@ -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 - -============= -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 `_ + +Team and repository tags +------------------------ + +.. image:: https://governance.openstack.org/tc/badges/python-tripleoclient.svg + :target: https://governance.openstack.org/tc/reference/tags/index.html diff --git a/doc/requirements.txt b/doc/requirements.txt index 81f92e29d..cd6430508 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 84cc5dba1..c351f931e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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' diff --git a/doc/source/index.rst b/doc/source/index.rst index 51abc7e0d..6371f78ab 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 -* :ref:`genindex` -* :ref:`search` + Indices and tables + ================== + + * :ref:`genindex` + * :ref:`search` diff --git a/tox.ini b/tox.ini index 0b670318e..c0acfaed1 100644 --- a/tox.ini +++ b/tox.ini @@ -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 =