diff --git a/bindep.txt b/bindep.txt
index d6b9595848..6226f9082d 100644
--- a/bindep.txt
+++ b/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]
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 3b4316c62f..d2f1ecd6a4 100644
--- a/doc/requirements.txt
+++ b/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
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 6130235a17..258c625fed 100644
--- a/doc/source/admin/index.rst
+++ b/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`
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 76f9abae52..ebb8f45371 100644
--- a/doc/source/conf.py
+++ b/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')
-openstack_logo = openstackdocstheme.get_theme_logo_path('openstackdocs')
+# Fix Unicode character for sphinx_feature_classification
+# 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"""
-\newcommand{\openstacklogo}{%s}
-\usepackage{%s}
-""" % (openstack_logo, pdf_theme_path)
+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
+ '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 -----------------------------------------------
diff --git a/doc/source/contributor/devref/erd.rst b/doc/source/contributor/devref/erd.rst
index c639b0e24f..e4a3c530a7 100644
--- a/doc/source/contributor/devref/erd.rst
+++ b/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
- :width: 660px
- :target: ../../_images/erd.svg
+ Click to enlarge the diagram.
+
+ .. image:: erd.svg
+ :width: 660px
+ :target: ../../_images/erd.svg
+
+.. only:: latex
+
+ .. image:: erd.svg
+ :width: 660px
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index d1bb63d09b..ec57e28a26 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -89,14 +89,22 @@ Version 1.1 (queens)
specs/version1.1/*
-Indices and Search
-------------------
-.. toctree::
- :hidden:
+.. only:: latex
- modules/modules
+ Module Reference
+ ----------------
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+ .. toctree::
+ :hidden:
+
+ modules/modules
+
+.. only:: html
+
+ Indices and Search
+ ------------------
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c2aae8e727..028067fbda 100644
--- a/doc/source/index.rst
+++ b/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 `_.
-To align with the overall OpenStack documentation, the Octavia documentation
-is grouped into the following topic areas.
+.. only:: html
+
+ 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`
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 4fc759f49f..2b0df0f291 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -9,9 +9,11 @@ Octavia Reference
*
Command Line Interface Reference
-Indices and Search
-------------------
+.. only:: html
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+ Indices and Search
+ ------------------
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index 7770b1d31d..9c12b65894 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -38,8 +38,10 @@ Videos
Introduction to OpenStack Load Balancing (2017 Boston Summit)
-Indices and Search
-------------------
+.. only:: html
-* :ref:`genindex`
-* :ref:`search`
+ Indices and Search
+ ------------------
+
+ * :ref:`genindex`
+ * :ref:`search`
diff --git a/lower-constraints.txt b/lower-constraints.txt
index 8625e4a2d4..6b6fc98a92 100644
--- a/lower-constraints.txt
+++ b/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
diff --git a/tools/create_flow_docs.py b/tools/create_flow_docs.py
index b2d8e16ab3..9466e0cfcd 100755
--- a/tools/create_flow_docs.py
+++ b/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(' :target: ../../../_images/' +
+ current_doc_file.write(' :width: 660px\n')
+ 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(' :target: ../../../_images/' +
+ current_doc_file.write(' :width: 660px\n')
+ 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()
diff --git a/tox.ini b/tox.ini
index 3ed0e8343b..97d93c1329 100644
--- a/tox.ini
+++ b/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}