PDF documentation build

It turns out that blank lines are not allowed in tables in
the latex builder. Otherwise, LaTeX complication fails.
A blank line in the docstring of 'bfd' class in os_ken/lib/packet/bfd.py
was dropped to pass LaTeX build.

Note that the structure of the generated PDF is not good (bad enough?).
This will be updated later.

Change-Id: Iec62042d4642d50d411478fadfa09e6a6bbf0a42
Story: 2006099
Task: 35137

doc/source/conf.py

@@ -68,15 +68,16 @@ html_theme = 'openstackdocs'
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
+# -- Options for LaTeX output -------------------------------------------------
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
+     'doc-%s.tex' % project,
      u'%s Documentation' % project,
      u'OpenStack Developers', 'manual'),
 ]
 
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+latex_use_xindy = False

doc/source/index.rst

@@ -36,9 +36,11 @@ Archived Contents:
    snort_integrate.rst
    app.rst
 
-Indices and tables
-==================
+.. only:: html
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   Indices and tables
+   ==================
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

os_ken/lib/packet/bfd.py

@@ -162,14 +162,13 @@ class bfd(packet_base.PacketBase):
                                    session state.
     state                          The current BFD session state as seen by
                                    the transmitting system.
-    flags                          Bitmap of the following flags.
-
-                                   | BFD_FLAG_POLL
-                                   | BFD_FLAG_FINAL
-                                   | BFD_FLAG_CTRL_PLANE_INDEP
-                                   | BFD_FLAG_AUTH_PRESENT
-                                   | BFD_FLAG_DEMAND
-                                   | BFD_FLAG_MULTIPOINT
+    flags                          Bitmap of the following flags:
+                                   ``BFD_FLAG_POLL``,
+                                   ``BFD_FLAG_FINAL``,
+                                   ``BFD_FLAG_CTRL_PLANE_INDEP``,
+                                   ``BFD_FLAG_AUTH_PRESENT``,
+                                   ``BFD_FLAG_DEMAND``,
+                                   ``BFD_FLAG_MULTIPOINT``
     detect_mult                    Detection time multiplier.
     my_discr                       My Discriminator.
     your_discr                     Your Discriminator.

tox.ini

@@ -44,6 +44,16 @@ basepython = python3
 deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -W -b html doc/source doc/build/html
 
+[testenv:pdf-docs]
+basepython = python3
+envdir = {toxworkdir}/docs
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  make
+commands =
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:releasenotes]
 basepython = python3
 deps = {[testenv:docs]deps}