From 791fefbf4edf00950405d06f15282371fdb30306 Mon Sep 17 00:00:00 2001 From: Michael Johnson Date: Fri, 13 Sep 2019 10:48:05 -0700 Subject: [PATCH] Generate PDF documentation Change-Id: If69b232cc2174bf00be4314dd71085100f4e951c Story: 2006101 Task: 35149 --- README.rst | 6 +- doc/requirements.txt | 3 + doc/source/conf.py | 95 +++++++++++++++++++++++++------ doc/source/index.rst | 20 +++---- octavia_tempest_plugin/version.py | 32 +++++++++++ tox.ini | 11 ++++ 6 files changed, 139 insertions(+), 28 deletions(-) create mode 100644 octavia_tempest_plugin/version.py diff --git a/README.rst b/README.rst index b2c74ee9..8b5bd3cc 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,7 @@ -======================== +====================== +Octavia Tempest Plugin +====================== + Team and repository tags ======================== @@ -7,7 +10,6 @@ Team and repository tags .. Change things from this point on -============================== Tempest integration of Octavia ============================== diff --git a/doc/requirements.txt b/doc/requirements.txt index ddf84119..90ae1152 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -9,3 +9,6 @@ openstackdocstheme>=1.18.1 # Apache-2.0 # releasenotes reno>=2.5.0 # Apache-2.0 + +# PDF Docs +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index 2d5c49ff..5bbe2959 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. +import datetime import os import sys @@ -29,7 +30,8 @@ extensions = [ 'sphinx.ext.viewcode', 'openstackdocstheme', 'oslo_config.sphinxext', - 'sphinxcontrib.apidoc' + 'sphinxcontrib.apidoc', + 'sphinxcontrib.rsvgconverter' ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -45,7 +47,17 @@ master_doc = 'index' # General information about the project. project = u'octavia-tempest-plugin' -copyright = u'2017, OpenStack Foundation' +copyright = u'2017-2019, OpenStack Foundation' + +# 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_tempest_plugin.version import version_info as octavia_tempest_ver +release = octavia_tempest_ver.release_string() +# The short X.Y version. +version = octavia_tempest_ver.version_string() # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -60,6 +72,14 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. modindex_common_prefix = ['octavia_tempest_plugin.'] +repository_name = 'openstack/octavia-tempest-plugin' +bug_project = '910' +bug_tag = 'docs' + +apidoc_output_dir = '_build/modules' +apidoc_module_dir = '../../octavia_tempest_plugin' +apidoc_excluded_paths = [] + # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with @@ -81,23 +101,66 @@ html_domain_indices = True # If false, no index is generated. html_use_index = True +# -- Options for LaTeX output ------------------------------------------------- + +# 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', - '%s.tex' % project, - u'%s Documentation' % project, - u'OpenStack Foundation', 'manual'), -] +latex_documents = [( + 'index', + 'doc-octavia-tempest-plugin.tex', + u'Octavia Tempest Plugin Documentation', + u'OpenStack Octavia Team', + 'manual' +)] -# Example configuration for intersphinx: refer to the Python standard library. -#intersphinx_mapping = {'http://docs.python.org/': None} +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None -repository_name = 'openstack/octavia-tempest-plugin' -bug_project = '910' -bug_tag = 'docs' +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False -apidoc_output_dir = '_build/modules' -apidoc_module_dir = '../../octavia_tempest_plugin' -apidoc_excluded_paths = [] +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +latex_domain_indices = False diff --git a/doc/source/index.rst b/doc/source/index.rst index 494a0b63..b991832d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,8 +6,6 @@ Welcome to octavia-tempest-plugin's documentation! ================================================== -Contents: - .. toctree:: :maxdepth: 2 @@ -16,14 +14,16 @@ Contents: contributing configref -Indices and tables -================== +.. only:: html -.. toctree:: - :hidden: + Indices and tables + ------------------ - _build/modules/modules + .. toctree:: + :hidden: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + _build/modules/modules + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/octavia_tempest_plugin/version.py b/octavia_tempest_plugin/version.py new file mode 100644 index 00000000..0f2cf15e --- /dev/null +++ b/octavia_tempest_plugin/version.py @@ -0,0 +1,32 @@ +# Copyright 2011-2014 OpenStack Foundation +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import pbr.version + +OCTAVIA_TEMPEST_VENDOR = "OpenStack Foundation" +OCTAVIA_TEMPEST_PRODUCT = "OpenStack Octavia tempest plugin" + +version_info = pbr.version.VersionInfo('octavia-tempest-plugin') + + +def vendor_string(): + return OCTAVIA_TEMPEST_VENDOR + + +def product_string(): + return OCTAVIA_TEMPEST_PRODUCT + + +def version_string_with_package(): + return version_info.version_string() diff --git a/tox.ini b/tox.ini index 1ca36b7f..33b941c1 100644 --- a/tox.ini +++ b/tox.ini @@ -49,6 +49,17 @@ commands = rm -rf doc/build sphinx-build -W -b html doc/source doc/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:releasenotes] basepython = python3 deps =