diff --git a/README.rst b/README.rst index d13bb84..6632dcf 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,3 @@ -======================== Team and repository tags ======================== @@ -7,7 +6,6 @@ Team and repository tags .. Change things from this point on -==================== python-octaviaclient ==================== diff --git a/doc/requirements.txt b/doc/requirements.txt index 6db47db..e9d0b93 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -5,4 +5,9 @@ sphinx>=1.6.2,!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7' # BSD sphinx>=1.6.2,!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4' # BSD openstackdocstheme>=1.20.0 # 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 acf6150..752c071 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', - 'cliff.sphinxext' + 'cliff.sphinxext', + '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'2016, OpenStack Foundation' +copyright = u'2016-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 octaviaclient.version import version_info as octavia_client_version +release = octavia_client_version.release_string() +# The short X.Y version. +version = octavia_client_version.version_string() # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -49,6 +61,13 @@ add_module_names = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# openstackdocstheme options +repository_name = 'openstack/python-octaviaclient' +bug_project = '911' +bug_tag = 'doc' + +autoprogram_cliff_application = 'openstack' + # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with @@ -66,22 +85,66 @@ html_theme_options = { # Output file base name for HTML help builder. htmlhelp_basename = 'python-octaviaclientdoc' +# -- 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', - 'python-octaviaclient.tex', - u'python-octaviaclient Documentation', - u'OpenStack Foundation', 'manual'), -] +latex_documents = [( + 'index', + 'doc-python-octaviaclient.tex', + u'Octavia Python Client 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 -# openstackdocstheme options -repository_name = 'openstack/python-octaviaclient' -bug_project = '911' -bug_tag = 'doc' +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False -autoprogram_cliff_application = 'openstack' +# 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 864c5d5..c4caea7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,8 +6,10 @@ Python Octavia Client ===================== -The Python Octavia Client (python-octaviaclient) is a command-line client for -the OpenStack Load Balancing service. +.. only:: html + + The Python Octavia Client (python-octaviaclient) is a command-line client + for the OpenStack Load Balancing service. Getting Started --------------- @@ -28,8 +30,10 @@ Usage cli/index reference/index -Indices and tables ------------------- +.. only:: html -* :ref:`genindex` -* :ref:`search` + Indices and tables + ------------------ + + * :ref:`genindex` + * :ref:`search` diff --git a/octaviaclient/osc/v2/pool.py b/octaviaclient/osc/v2/pool.py index 7bac8dd..708dadf 100644 --- a/octaviaclient/osc/v2/pool.py +++ b/octaviaclient/osc/v2/pool.py @@ -92,7 +92,7 @@ class CreatePool(command.ShowOne): '--tls-container-ref', metavar='', help="The reference to the key manager service secrets container " - "containing the certificate and key for ``tls_enabled``" + "containing the certificate and key for ``tls_enabled`` " "pools to re-encrpt the traffic to backend member servers." ) parser.add_argument( diff --git a/octaviaclient/version.py b/octaviaclient/version.py new file mode 100644 index 0000000..7aa3980 --- /dev/null +++ b/octaviaclient/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_CLIENT_VENDOR = "OpenStack Foundation" +OCTAVIA_CLIENT_PRODUCT = "OpenStack Octavia client" + +version_info = pbr.version.VersionInfo('python-octaviaclient') + + +def vendor_string(): + return OCTAVIA_CLIENT_VENDOR + + +def product_string(): + return OCTAVIA_CLIENT_PRODUCT + + +def version_string_with_package(): + return version_info.version_string() diff --git a/tox.ini b/tox.ini index da994fa..6cbcb2f 100644 --- a/tox.ini +++ b/tox.ini @@ -51,8 +51,19 @@ deps = -r{toxinidir}/requirements.txt -r{toxinidir}/doc/requirements.txt commands = - rm -rf doc/build - sphinx-build -b html doc/source doc/build/html + rm -rf doc/build/html + 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