From 16b9486bf7e91bfd5dc48297cee9f54b49156c93 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Fri, 16 Aug 2019 00:52:14 +0900 Subject: [PATCH] PDF documentation build - Add a new pdf-docs environment to enable PDF build. - sphinxcontrib-svg2pdfconverter is used to handle SVG properly. - maxlistdepth=10 in latex_elements is needed to handle deeper levels of nesting. - Sample config/policy files are skipped in the PDF document as inline sample files cause LaTeX error [1] and direct links in PDF doc is discouraged. Note that sample-config and sample-policy need to be excluded to avoid the LaTeX error [1] and :orphan: is specified in those files. [1] https://github.com/sphinx-doc/sphinx/issues/3099 Change-Id: I3aaea1d15a357f550f529beaa84fb1a1a7748358 --- doc/requirements.txt | 3 ++- doc/source/conf.py | 5 ++++- doc/source/configuration/config.rst | 5 ++++- doc/source/configuration/index.rst | 25 +++++++++++++++++++------ doc/source/configuration/policy.rst | 7 +++++-- tox.ini | 13 ++++++++++++- 6 files changed, 46 insertions(+), 12 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index c134946f81ca..c0a868a619c7 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,9 +2,10 @@ # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD -sphinx>=1.8.0;python_version>='3.4' # BSD +sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD sphinxcontrib-actdiag>=0.8.5 # BSD sphinxcontrib-seqdiag>=0.8.4 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD sphinx-feature-classification>=0.2.0 # Apache-2.0 os-api-ref>=1.4.0 # Apache-2.0 openstackdocstheme>=1.30.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index ecfc6f5fb376..49095c29cae5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -43,6 +43,7 @@ extensions = [ 'ext.feature_matrix', 'sphinxcontrib.actdiag', 'sphinxcontrib.seqdiag', + 'sphinxcontrib.rsvgconverter', ] # openstackdocstheme options @@ -123,10 +124,12 @@ html_extra_path = ['_extra'] # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ - ('index', 'Nova.tex', u'Nova Documentation', + ('index', 'doc-nova.tex', u'Nova Documentation', u'OpenStack Foundation', 'manual'), ] +# Allow deeper levels of nesting for \begin...\end stanzas +latex_elements = {'maxlistdepth': 10} # -- Options for openstackdocstheme ------------------------------------------- diff --git a/doc/source/configuration/config.rst b/doc/source/configuration/config.rst index 8dd6394adc36..571c84e78f52 100644 --- a/doc/source/configuration/config.rst +++ b/doc/source/configuration/config.rst @@ -3,7 +3,10 @@ Configuration Options ===================== The following is an overview of all available configuration options in Nova. -For a sample configuration file, refer to :doc:`/configuration/sample-config`. + +.. only:: html + + For a sample configuration file, refer to :doc:`sample-config`. .. show-options:: :config-file: etc/nova/nova-config-generator.conf diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index e82ba862624c..b59a63b4bb52 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -17,8 +17,10 @@ Configuration * :doc:`Config Reference `: A complete reference of all configuration options available in the ``nova.conf`` file. -* :doc:`Sample Config File `: A sample config - file with inline documentation. +.. only:: html + + * :doc:`Sample Config File `: A sample config + file with inline documentation. Policy ------ @@ -29,8 +31,10 @@ permissions on REST API actions. * :doc:`Policy Reference `: A complete reference of all policy points in nova and what they impact. -* :doc:`Sample Policy File `: A sample nova - policy file with inline documentation. +.. only:: html + + * :doc:`Sample Policy File `: A sample nova + policy file with inline documentation. .. # NOTE(mriedem): This is the section where we hide things that we don't # actually want in the table of contents but sphinx build would fail if @@ -39,6 +43,15 @@ permissions on REST API actions. :hidden: config - sample-config policy - sample-policy + +.. # NOTE(amotoki): Sample files are only available in HTML document. + # Inline sample files with literalinclude hit LaTeX processing error + # like TeX capacity exceeded and direct links are discouraged in PDF doc. +.. only:: html + + .. toctree:: + :hidden: + + sample-config + sample-policy diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst index 66b4c7982d3c..60c8fa500501 100644 --- a/doc/source/configuration/policy.rst +++ b/doc/source/configuration/policy.rst @@ -2,8 +2,11 @@ Nova Policies ============= -The following is an overview of all available policies in Nova. For a sample -configuration file, refer to :doc:`/configuration/sample-policy`. +The following is an overview of all available policies in Nova. + +.. only:: html + + For a sample configuration file, refer to :doc:`sample-policy`. .. show-policy:: :config-file: etc/nova/nova-policy-generator.conf diff --git a/tox.ini b/tox.ini index 243b0014e808..ee093c184d6e 100644 --- a/tox.ini +++ b/tox.ini @@ -14,6 +14,7 @@ whitelist_externals = find rm env + make install_command = pip install -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} {opts} {packages} setenv = VIRTUAL_ENV={envdir} @@ -167,7 +168,7 @@ description = Build main documentation. deps = -r{toxinidir}/doc/requirements.txt commands = - rm -rf doc/build + rm -rf doc/build/html doc/build/doctrees # Check that all JSON files don't have \r\n in line. bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'" # Check that all included JSON files are valid JSON @@ -176,6 +177,16 @@ commands = # Test the redirects. This must run after the main docs build whereto doc/build/html/.htaccess doc/test/redirect-tests.txt +[testenv:pdf-docs] +description = + Build PDF documentation. +envdir = {toxworkdir}/docs +deps = {[testenv:docs]deps} +commands = + rm -rf doc/build/pdf + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf + [testenv:api-guide] description = Generate the API guide. Called from CI scripts to test and publish to docs.openstack.org.