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

@@ -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

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

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

doc/source/configuration/index.rst

@@ -17,8 +17,10 @@ Configuration
 * :doc:`Config Reference <config>`: A complete reference of all
   configuration options available in the ``nova.conf`` file.
 
-* :doc:`Sample Config File <sample-config>`: A sample config
-  file with inline documentation.
+.. only:: html
+
+   * :doc:`Sample Config File <sample-config>`: A sample config
+     file with inline documentation.
 
 Policy
 ------
@@ -29,8 +31,10 @@ permissions on REST API actions.
 * :doc:`Policy Reference <policy>`: A complete reference of all
   policy points in nova and what they impact.
 
-* :doc:`Sample Policy File <sample-policy>`: A sample nova
-  policy file with inline documentation.
+.. only:: html
+
+   * :doc:`Sample Policy File <sample-policy>`: 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

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

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.