From e10b094db4b329d89674d7ce8fd4f37bfd16740b Mon Sep 17 00:00:00 2001 From: "Walter A. Boring IV" Date: Mon, 19 Aug 2019 14:24:58 -0700 Subject: [PATCH] Add pdf documentation build in tox This patch adds a new tox job/command for building the pdf version of documentation. tox -epdf-docs In addition to adjusting the infra requirement for PDF build support, the following changes are made to build a PDF doc. - Inline sample config file is skipped for PDF doc to avoid an LaTeX error "TeX capacity exceeded". - Download link of sample config and policy files are disabled for PDF doc as relative links do not make sense. - "Search" and "genindex" page is only enabled for HTML doc as they work only for HTML doc. Co-Authored-By: Akihiro Motoki Change-Id: Ib8ce96f4d043dcf0cfe6d3f8b64879f07bc5958c --- doc/source/conf.py | 14 +++++++++++++- .../block-storage/samples/cinder.conf.rst | 15 +++++++++++---- .../block-storage/samples/policy.yaml.rst | 6 ++++-- doc/source/contributor/index.rst | 12 +++++++----- doc/source/index.rst | 13 ++++++++----- tox.ini | 15 ++++++++++++++- 6 files changed, 57 insertions(+), 18 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index b6e3411ba0f..140a791bdcf 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -227,7 +227,7 @@ htmlhelp_basename = 'cinderdoc' # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ - ('index', 'Cinder.tex', u'Cinder Documentation', + ('index', 'cinder.tex', u'Cinder Documentation', u'Cinder Contributors', 'manual'), ] @@ -247,3 +247,15 @@ latex_documents = [ # If false, no module index is generated. # latex_use_modindex = True + +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + +latex_domain_indices = False + +latex_elements = { + 'makeindex': '', + 'printindex': '', + 'preamble': r'\setcounter{tocdepth}{3}', + 'maxlistdepth': 10, +} diff --git a/doc/source/configuration/block-storage/samples/cinder.conf.rst b/doc/source/configuration/block-storage/samples/cinder.conf.rst index 65937fc6bcd..5f75429ceb9 100644 --- a/doc/source/configuration/block-storage/samples/cinder.conf.rst +++ b/doc/source/configuration/block-storage/samples/cinder.conf.rst @@ -6,8 +6,15 @@ The ``cinder.conf`` file is installed in ``/etc/cinder`` by default. When you manually install the Block Storage service, the options in the ``cinder.conf`` file are set to default values. -The sample configuration file can also be viewed in -`file form <../../../_static/cinder.conf.sample>`_. +.. only:: html -.. literalinclude:: ../../../_static/cinder.conf.sample - :language: ini + The sample configuration file can also be viewed in + `file form <../../../_static/cinder.conf.sample>`_. + + .. literalinclude:: ../../../_static/cinder.conf.sample + :language: ini + +.. only:: latex + + See the on-line version of this documentation for the full example + config file. diff --git a/doc/source/configuration/block-storage/samples/policy.yaml.rst b/doc/source/configuration/block-storage/samples/policy.yaml.rst index 954c02a7183..98e15d1cb53 100644 --- a/doc/source/configuration/block-storage/samples/policy.yaml.rst +++ b/doc/source/configuration/block-storage/samples/policy.yaml.rst @@ -31,7 +31,9 @@ The following provides a listing of the default policies. It is not recommended to copy this file into ``/etc/cinder`` unless you are planning on providing a different policy for an operation that is not the default. -The sample policy file can also be viewed in `file form -<../../../_static/cinder.policy.yaml.sample>`_. +.. only:: html + + The sample policy file can also be viewed in `file form + <../../../_static/cinder.policy.yaml.sample>`_. .. literalinclude:: ../../../_static/cinder.policy.yaml.sample diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 4e8ecc3c551..fe438330c69 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -82,10 +82,12 @@ Other Resources Module Reference -Indices and tables ------------------- +.. only:: html -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + Indices and tables + ------------------ + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/doc/source/index.rst b/doc/source/index.rst index f371a32af7c..0838be0923f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -152,10 +152,13 @@ Contents: common/glossary.rst -Indices and tables -~~~~~~~~~~~~~~~~~~ -Contents: +.. only:: html -* :ref:`genindex` -* :ref:`search` + Indices and tables + ~~~~~~~~~~~~~~~~~~ + + Contents: + + * :ref:`genindex` + * :ref:`search` diff --git a/tox.ini b/tox.ini index c89569958ff..b2ea64c5636 100644 --- a/tox.ini +++ b/tox.ini @@ -136,10 +136,23 @@ deps = -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} -r{toxinidir}/doc/requirements.txt commands = - rm -fr doc/build doc/source/contributor/api/ .autogenerated + rm -fr doc/source/contributor/api/ + rm -fr doc/build/html doc/build/doctrees sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html whitelist_externals = rm +[testenv:pdf-docs] +basepython = python3 +deps = {[testenv:docs]deps} +commands = + rm -fr doc/source/contributor/api/ + rm -fr doc/build/pdf + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf +whitelist_externals = + make + rm + [testenv:gendriverlist] basepython = python3 sitepackages = False