Generate PDF documentation

This patch sets up PDF document generation for Octavia.

Story: 2006101
Task: 35146
Change-Id: I076335d08d5411fd629c3e8860f14980b0dbcb5a

bindep.txt

@@ -1,2 +1,27 @@
 # Docs package dependencies
 graphviz [doc]
+# PDF Docs package dependencies
+make [doc]
+fonts-freefont-otf [doc platform:dpkg]
+fonts-liberation [doc platform:dpkg]
+texlive-latex-base [doc platform:dpkg]
+texlive-latex-extra [doc platform:dpkg]
+texlive-xetex [doc platform:dpkg]
+texlive-fonts-recommended [doc platform:dpkg]
+xindy [doc platform:dpkg]
+latexmk [doc platform:dpkg]
+texlive [doc platform:rpm]
+texlive-fncychap [doc platform:rpm]
+texlive-titlesec [doc platform:rpm]
+texlive-tabulary [doc platform:rpm]
+texlive-framed [doc platform:rpm]
+texlive-wrapfig [doc platform:rpm]
+texlive-upquote [doc platform:rpm]
+texlive-capt-of [doc platform:rpm]
+texlive-needspace [doc platform:rpm]
+texlive-polyglossia [doc platform:rpm]
+texlive-xindy [doc platform:rpm]
+latexmk [doc platform:rpm]
+python3-sphinxcontrib-svg2pdfconverter-common [doc platform:rpm]
+librsvg2-tools [doc platform:rpm]
+librsvg2-bin [doc platform:dpkg]

doc/requirements.txt

@@ -17,6 +17,9 @@ sadisplay>=0.4.8 # BSD
 reno>=2.5.0 # Apache-2.0
 sphinx-feature-classification>=0.2.0 # Apache-2.0
 
+# PDF Docs
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+
 # This needs to be installed after above modules
 pydot>=1.2.4 # MIT License
 pydotplus>=2.0.2 # MIT License

doc/source/admin/index.rst

@@ -41,7 +41,9 @@ Operator Reference
    guides/upgrade.rst
    apache-httpd.rst
 
-Indices and Search
+.. only:: html
-------------------
 
-* :ref:`search`
+   Indices and Search
+   ------------------
+
+   * :ref:`search`

doc/source/conf.py

@@ -12,10 +12,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import os
 import sys
 
-import openstackdocstheme
 from pydotplus import graphviz
 import sadisplay
 
@@ -66,7 +66,8 @@ extensions = [
     'openstackdocstheme',
     'oslo_config.sphinxext',
     'oslo_policy.sphinxpolicygen',
-    'sphinxcontrib.apidoc'
+    'sphinxcontrib.apidoc',
+    'sphinxcontrib.rsvgconverter',
 ]
 
 todo_include_todos = True
@@ -84,7 +85,17 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-copyright = u'2014, OpenStack Octavia Team'
+copyright = u'2014-2019, OpenStack Octavia Team'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# Version info
+from octavia.version import version_info as octavia_version
+release = octavia_version.release_string()
+# The short X.Y version.
+version = octavia_version.version_string()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -204,20 +215,43 @@ htmlhelp_basename = 'Octavia-Specsdoc'
 
 # -- Options for LaTeX output -------------------------------------------------
 
-pdf_theme_path = openstackdocstheme.get_pdf_theme_path('openstackdocs')
+# Fix Unicode character for sphinx_feature_classification
-openstack_logo = openstackdocstheme.get_theme_logo_path('openstackdocs')
+# Sphinx default latex engine (pdflatex) doesn't know much unicode
+latex_preamble = r"""
+\usepackage{newunicodechar}
+\newunicodechar{✖}{\sffamily X}
+\setcounter{tocdepth}{2}
+\authoraddress{\textcopyright %s OpenStack Foundation}
+""" % datetime.datetime.now().year
 
-latex_custom_template = r"""
+latex_elements = {
-\newcommand{\openstacklogo}{%s}
+    # The paper size ('letterpaper' or 'a4paper').
-\usepackage{%s}
+    # 'papersize': 'letterpaper',
-""" % (openstack_logo, pdf_theme_path)
+
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    # openany: Skip blank pages in generated PDFs
+    'extraclassoptions': 'openany,oneside',
+    'makeindex': '',
+    'printindex': '',
+    'preamble': latex_preamble
+}
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+# Some distros are missing xindy
+latex_use_xindy = False
+
+# Fix missing apostrophe
+smartquotes_excludes = {'builders': ['latex']}
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [(
     'index',
-    'Octavia.tex',
+    'doc-octavia.tex',
     u'Octavia Documentation',
     u'OpenStack Octavia Team',
     'manual'
@@ -241,7 +275,7 @@ latex_documents = [(
 # latex_appendices = []
 
 # If false, no module index is generated.
-# latex_domain_indices = True
+latex_domain_indices = False
 
 # -- Options for Texinfo output -----------------------------------------------
 

doc/source/contributor/devref/erd.rst

@@ -10,8 +10,15 @@ Below is the current Octavia database data model.
 * Items labeled as "PROPERTY" are data model relationships and are not
   present in the database.
 
-Click to enlarge the diagram.
+.. only:: html
 
-.. image:: erd.svg
+   Click to enlarge the diagram.
-    :width: 660px
+
-    :target: ../../_images/erd.svg
+   .. image:: erd.svg
+       :width: 660px
+       :target: ../../_images/erd.svg
+
+.. only:: latex
+
+   .. image:: erd.svg
+       :width: 660px

doc/source/contributor/index.rst

@@ -89,14 +89,22 @@ Version 1.1 (queens)
 
    specs/version1.1/*
 
-Indices and Search
-------------------
 
-.. toctree::
+.. only:: latex
-   :hidden:
 
-   modules/modules
+   Module Reference
+   ----------------
 
-* :ref:`genindex`
+   .. toctree::
-* :ref:`modindex`
+      :hidden:
-* :ref:`search`
+
+      modules/modules
+
+.. only:: html
+
+   Indices and Search
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

doc/source/index.rst

@@ -11,8 +11,10 @@ See :doc:`reference/introduction` for an overview of Octavia.
 
 For information on what is new see the `Octavia Release Notes <https://docs.openstack.org/releasenotes/octavia/>`_.
 
-To align with the overall OpenStack documentation, the Octavia documentation
+.. only:: html
-is grouped into the following topic areas.
+
+   To align with the overall OpenStack documentation, the Octavia documentation
+   is grouped into the following topic areas.
 
 .. toctree::
    :maxdepth: 1
@@ -26,6 +28,6 @@ is grouped into the following topic areas.
    reference/index.rst
    user/index.rst
 
+.. only:: html
 
-
+   :ref:`search`
-:ref:`search`

doc/source/reference/index.rst

@@ -9,9 +9,11 @@ Octavia Reference
    *
    Command Line Interface Reference <https://docs.openstack.org/python-octaviaclient/latest/cli/index.html>
 
-Indices and Search
+.. only:: html
-------------------
 
-* :ref:`genindex`
+   Indices and Search
-* :ref:`modindex`
+   ------------------
-* :ref:`search`
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

doc/source/user/index.rst

@@ -38,8 +38,10 @@ Videos
 
    Introduction to OpenStack Load Balancing (2017 Boston Summit) <https://youtu.be/BBgP3_qhJ00>
 
-Indices and Search
+.. only:: html
-------------------
 
-* :ref:`genindex`
+   Indices and Search
-* :ref:`search`
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`search`

lower-constraints.txt

@@ -145,6 +145,7 @@ six==1.10.0
 smmap2==2.0.3
 snowballstemmer==1.2.1
 Sphinx==1.6.2
+sphinxcontrib-svg2pdfconverter==0.1.0
 sphinxcontrib-websupport==1.0.1
 SQLAlchemy==1.0.10
 sqlalchemy-migrate==0.11.0

tools/create_flow_docs.py

@@ -102,12 +102,20 @@ def generate(flow_list, output_directory):
             current_doc_file.write(doc_tuple[1] + '\n')
             current_doc_file.write('-' * len(doc_tuple[1]) + '\n')
             current_doc_file.write('\n')
-            current_doc_file.write('.. image:: ' + doc_tuple[0] +
+            current_doc_file.write('.. only:: html\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('   .. image:: ' + doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
-            current_doc_file.write('    :width: 660px\n')
+            current_doc_file.write('       :width: 660px\n')
-            current_doc_file.write('    :target: ../../../_images/' +
+            current_doc_file.write('       :target: ../../../_images/' +
                                    doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('.. only:: latex\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('   .. image:: ' + doc_tuple[0] +
+                                   '-' + doc_tuple[1] + '.svg\n')
+            current_doc_file.write('       :width: 660px\n')
 
         # First or new class, create the file
         else:
@@ -128,17 +136,27 @@ def generate(flow_list, output_directory):
             current_doc_file.write('   :depth: 2\n')
             current_doc_file.write('   :backlinks: top\n')
             current_doc_file.write('\n')
-            current_doc_file.write('Click on any flow to view full size.\n')
+            current_doc_file.write('.. only:: html\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('   Click on any flow to view full size.\n')
             current_doc_file.write('\n')
             current_doc_file.write(doc_tuple[1] + '\n')
             current_doc_file.write('-' * len(doc_tuple[1]) + '\n')
             current_doc_file.write('\n')
-            current_doc_file.write('.. image:: ' + doc_tuple[0] +
+            current_doc_file.write('.. only:: html\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('   .. image:: ' + doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
-            current_doc_file.write('    :width: 660px\n')
+            current_doc_file.write('       :width: 660px\n')
-            current_doc_file.write('    :target: ../../../_images/' +
+            current_doc_file.write('       :target: ../../../_images/' +
                                    doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('.. only:: latex\n')
+            current_doc_file.write('\n')
+            current_doc_file.write('   .. image:: ' + doc_tuple[0] +
+                                   '-' + doc_tuple[1] + '.svg\n')
+            current_doc_file.write('       :width: 660px\n')
 
     current_doc_file.close()
 

tox.ini

@@ -96,6 +96,17 @@ commands =
   sphinx-build -W -b html doc/source doc/build/html
   sphinx-build -W -b html api-ref/source api-ref/build/html
 
+[testenv:pdf-docs]
+basepython = python3
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  make
+  rm
+commands =
+  rm -rf doc/build/pdf
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:venv]
 basepython = python3
 commands = {posargs}