Generate PDF documentation

- 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.
- Specify openany in extraclassoptions to skip blank pages
  (oneside is also specified to use the same page layout
   for even and odd pages)
- tocdepth is set to 2 for better PDF TOC
- printindex and makeindex are set to empty in latex_elements
  to avoid an empty "Index" section in PDF
- 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: I70100a71114e1d75833e6c783086325baa0e3fd2

doc/requirements.txt

@@ -2,11 +2,11 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
-sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7'  # BSD
-sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4'  # BSD
+sphinx>=1.8.0,!=2.1.0 # BSD
 sphinxcontrib-httpdomain>=1.3.0 # BSD
 sphinxcontrib-pecanwsme>=0.2 # Apache-2.0
 sphinxcontrib-seqdiag>=0.8.4 # BSD
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
 reno>=2.5.0 # Apache-2.0
 os-api-ref>=1.4.0 # Apache-2.0
 openstackdocstheme>=1.20.0 # Apache-2.0

doc/source/conf.py

@@ -22,12 +22,12 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
     'openstackdocstheme',
     'oslo_config.sphinxconfiggen',
     'oslo_config.sphinxext',
     'oslo_policy.sphinxext',
     'oslo_policy.sphinxpolicygen',
+    'sphinxcontrib.rsvgconverter',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -85,13 +85,35 @@ htmlhelp_basename = 'cyborgdoc'
 html_title = 'Cyborg'
 html_theme = 'openstackdocs'
 
+# -- Options for LaTeX output -------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    # openany: Skip blank pages in generated PDFs
+    'maxlistdepth': 10,
+    'extraclassoptions': 'openany,oneside',
+    'preamble': r'\setcounter{tocdepth}{2}',
+    'makeindex': '',
+    'printindex': '',
+}
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+# Some distros are missing xindy
+latex_use_xindy = False
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
     ('index',
-     'cyborg.tex',
-     u'cyborg Documentation',
+     'doc-cyborg.tex',
+     u'Cyborg Documentation',
      u'OpenStack Foundation', 'manual'),
 ]
 

doc/source/configuration/sample_config.rst

@@ -2,11 +2,21 @@
 Cyborg Configuration Sample
 ===========================
 
-The following is a sample cyborg configuration for adaptation and use. It is
-auto-generated from cyborg when this documentation is built, so if you are
-having issues with an option, please compare your version of cyborg with the
-version of this documentation.
+.. NOTE(acewit): literalinclude of sample config files causes
+   LaTeX error (TeX capacity exceeded), so they are skipped in PDF version.
 
-The sample configuration can also be downloaded in `file form <../_static/cyborg.conf.sample>`_.
+.. only:: latex
 
-.. literalinclude:: ../_static/cyborg.conf.sample
+   Sample configuration files for all Cyborg services are found in
+   the online version of this documentation.
+
+.. only:: html
+
+   The following is a sample cyborg configuration for adaptation and use. It is
+   auto-generated from cyborg when this documentation is built, so if you are
+   having issues with an option, please compare your version of cyborg with the
+   version of this documentation.
+
+   The sample configuration can also be downloaded in `file form <../_static/cyborg.conf.sample>`_.
+
+   .. literalinclude:: ../_static/cyborg.conf.sample

tox.ini

@@ -9,7 +9,9 @@ ignore_basepython_conflict = True
 
 [testenv]
 usedevelop = True
-whitelist_externals = rm
+whitelist_externals =
+  rm
+  make
 install_command = {[testenv:common-constraints]install_command}
 basepython = python3
 setenv =
@@ -78,8 +80,17 @@ ignore-path = .venv,.git,.tox,*cyborg/locale*,*lib/python*,*cyborg.egg*,api-ref/
 [testenv:docs]
 deps = -r{toxinidir}/doc/requirements.txt
 commands =
+    rm -rf doc/build/html
     sphinx-build -W -b html doc/source doc/build/html
 
+[testenv:pdf-docs]
+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:releasenotes]
 deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -W -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html