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}