diff --git a/doc/requirements.txt b/doc/requirements.txt index 799550c..47e0bee 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -4,3 +4,6 @@ openstackdocstheme>=1.20.0 # Apache-2.0 sphinxcontrib-apidoc>=0.2.1 # BSD # 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 49886c6..185fc5b 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 @@ -23,7 +24,8 @@ sys.path.insert(0, os.path.abspath('../..')) extensions = [ 'sphinx.ext.autodoc', 'openstackdocstheme', - 'sphinxcontrib.apidoc' + 'sphinxcontrib.apidoc', + 'sphinxcontrib.rsvgconverter' ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -37,7 +39,17 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -copyright = u'2018, OpenStack Developers' +copyright = u'2018-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_lib.version import version_info as octavia_lib_version +release = octavia_lib_version.release_string() +# The short X.Y version. +version = octavia_lib_version.version_string() # openstackdocstheme options repository_name = 'openstack/octavia-lib' @@ -74,15 +86,66 @@ html_theme = 'openstackdocs' # Output file base name for HTML help builder. htmlhelp_basename = 'octavia-libdoc' +# -- 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', - 'octavia-lib.tex', - u'octavia-lib Documentation', - u'OpenStack Developers', 'manual'), -] +latex_documents = [( + 'index', + 'doc-octavia-lib.tex', + u'Octavia Library 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 + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# 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 14a25e0..863543b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,14 +3,38 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -=========================================== Welcome to the documentation of Octavia lib =========================================== -.. include:: ../../README.rst +.. only:: html -octavia-lib Documentation: --------------------------------- + .. include:: ../../README.rst + +.. only:: latex + + .. image:: https://governance.openstack.org/tc/badges/octavia-lib.svg + + A library to support Octavia provider drivers. + + This python module provides a python library for Octavia provider driver + developers. + + See the provider driver development guide for more information: + + https://docs.openstack.org/octavia/latest/contributor/guides/providers.html + + Octavia-lib is distributed under the terms of the Apache License, Version 2.0. + The full terms and conditions of this license are detailed in the LICENSE file. + + * Free software: Apache license + * Documentation: https://docs.openstack.org/octavia-lib/latest + * Source: https://opendev.org/openstack/octavia-lib + * Bugs: https://storyboard.openstack.org/#!/project/openstack/octavia-lib + +.. only:: html + + octavia-lib Documentation: + -------------------------- .. toctree:: :maxdepth: 1 @@ -24,9 +48,11 @@ octavia-lib Documentation: admin/index reference/index -Indices and tables -================== +.. only:: html -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + Indices and tables + ------------------ + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/doc/source/library/index.rst b/doc/source/library/index.rst index c973734..c674cab 100644 --- a/doc/source/library/index.rst +++ b/doc/source/library/index.rst @@ -4,9 +4,11 @@ Usage Instructions for using the library are provided in the `Provider Driver Development Guide `_. -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/reference/index.rst b/doc/source/reference/index.rst index 06489ef..166153c 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -11,14 +11,21 @@ References Octavia Project Documentation Octavia API Reference -Indices and Search ------------------- +.. only: html -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + Indices and Search + ------------------ -.. toctree:: - :hidden: + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` - modules/modules +.. only:: latex + + Module Reference + ---------------- + + .. toctree:: + :hidden: + + modules/modules diff --git a/lower-constraints.txt b/lower-constraints.txt index 56145d1..b6c825c 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -11,6 +11,7 @@ pbr==2.0.0 pylint==1.9.2 python-subunit==1.0.0 six==1.10.0 +sphinxcontrib-svg2pdfconverter==0.1.0 stestr==2.0.0 tenacity==5.0.2 testtools==2.2.0 diff --git a/octavia_lib/version.py b/octavia_lib/version.py new file mode 100644 index 0000000..0811708 --- /dev/null +++ b/octavia_lib/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_LIB_VENDOR = "OpenStack Foundation" +OCTAVIA_LIB_PRODUCT = "OpenStack Octavia library" + +version_info = pbr.version.VersionInfo('octavia-lib') + + +def vendor_string(): + return OCTAVIA_LIB_VENDOR + + +def product_string(): + return OCTAVIA_LIB_PRODUCT + + +def version_string_with_package(): + return version_info.version_string() diff --git a/tox.ini b/tox.ini index 4bf32e2..40acbd7 100644 --- a/tox.ini +++ b/tox.ini @@ -52,6 +52,17 @@ commands = rm -rf doc/build doc/source/reference/modules 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 = {[testenv:docs]deps}