openstack/octavia
Code Issues Proposed changes

Generate PDF documentation

Browse Source 
This patch sets up PDF document generation for Octavia.

Story: 2006101
Task: 35146
Change-Id: I076335d08d5411fd629c3e8860f14980b0dbcb5a
This commit is contained in:
Michael Johnson 2019-06-24 16:45:13 -07:00
parent 9ec9859bbf
commit 97058e925b
12 changed files with 161 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
bindep.txt
View File

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

3
doc/requirements.txt
View File

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

8
doc/source/admin/index.rst
View File

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

56
doc/source/conf.py
View File

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

15
doc/source/contributor/devref/erd.rst
View File

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

24
doc/source/contributor/index.rst
View File

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

10
doc/source/index.rst
View File

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

12
doc/source/reference/index.rst
View File

@ -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`
* :ref:`modindex`
* :ref:`search`
Indices and Search
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

10
doc/source/user/index.rst
View File

@ -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`
* :ref:`search`
Indices and Search
------------------
* :ref:`genindex`
* :ref:`search`

1
lower-constraints.txt
View File

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

32
tools/create_flow_docs.py
View File

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

11
tox.ini
View File

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