Browse Source

Generate PDF documentation

This patch sets up PDF document generation for Octavia.

Story: 2006101
Task: 35146
Change-Id: I076335d08d5411fd629c3e8860f14980b0dbcb5a
changes/49/667249/12
Michael Johnson 2 years ago
parent
commit
97058e925b
  1. 25
      bindep.txt
  2. 3
      doc/requirements.txt
  3. 8
      doc/source/admin/index.rst
  4. 58
      doc/source/conf.py
  5. 15
      doc/source/contributor/devref/erd.rst
  6. 24
      doc/source/contributor/index.rst
  7. 10
      doc/source/index.rst
  8. 12
      doc/source/reference/index.rst
  9. 10
      doc/source/user/index.rst
  10. 1
      lower-constraints.txt
  11. 32
      tools/create_flow_docs.py
  12. 11
      tox.ini

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

3
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

8
doc/source/admin/index.rst

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

58
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')
latex_custom_template = r"""
\newcommand{\openstacklogo}{%s}
\usepackage{%s}
""" % (openstack_logo, pdf_theme_path)
# 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_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

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

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

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

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

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

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

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

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

Loading…
Cancel
Save