From b642742af0c3bdab3e1fa608f3ba3bb042cc4617 Mon Sep 17 00:00:00 2001 From: manchandavishal Date: Thu, 29 Aug 2019 14:50:32 +0000 Subject: [PATCH] Generate PDF documentation Story: 2006101 Task: 35147 Change-Id: Idc1f1f76d2decf28924f6cdb3c5f0a3491bb8e59 --- README.rst | 6 +- doc/requirements.txt | 7 ++- doc/source/conf.py | 125 +++++++++++++++++++++++++++++---------- doc/source/index.rst | 4 +- doc/source/reference.rst | 22 ++++--- tox.ini | 12 +++- 6 files changed, 129 insertions(+), 47 deletions(-) diff --git a/README.rst b/README.rst index 75ccbdf4..da701953 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,7 @@ -======================== +================= +Octavia Dashboard +================= + Team and repository tags ======================== @@ -7,7 +10,6 @@ Team and repository tags .. Change things from this point on -================= octavia-dashboard ================= diff --git a/doc/requirements.txt b/doc/requirements.txt index ca069c3f..69e79a8c 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,7 +2,12 @@ # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. openstackdocstheme>=1.20.0 # Apache-2.0 -reno>=2.5.0 # Apache-2.0 sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD sphinx!=1.6.6,!=1.6.7,>=1.6.2,!=2.1.0;python_version>='3.4' # BSD 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 deb27a8d..ae4a85a2 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 logging import os import sys @@ -35,10 +36,10 @@ extensions = [ 'openstackdocstheme', 'sphinx.ext.autodoc', 'sphinx.ext.coverage', - # 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode', - 'sphinxcontrib.apidoc' + 'sphinxcontrib.apidoc', + 'sphinxcontrib.rsvgconverter' ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -52,7 +53,17 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -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_dashboard.version import version_info as octavia_dash_version +release = octavia_dash_version.release_string() +# The short X.Y version. +version = octavia_dash_version.version_string() # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -64,6 +75,23 @@ add_module_names = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# openstackdocstheme options +repository_name = 'openstack/octavia-dashboard' +use_storyboard = True + +apidoc_output_dir = 'contributor/modules' +apidoc_module_dir = '../../octavia_dashboard' +apidoc_excluded_paths = [ + 'tests', + 'enabled', + 'locale', + 'static', + 'conf', + 'local_settings.d', + 'post_install.sh', + 'karma.conf.js' +] + # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with @@ -82,36 +110,69 @@ html_static_path = [] # Output file base name for HTML help builder. htmlhelp_basename = 'octavia-dashboarddoc' -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto/manual]). -latex_documents = [ - ('index', - 'octavia-dashboard.tex', - u'octavia-dashboard Documentation', - u'OpenStack Foundation', 'manual'), -] - -# Example configuration for intersphinx: refer to the Python standard library. -# intersphinx_mapping = {'http://docs.python.org/': None} - # A list of ignored prefixes for module index sorting. modindex_common_prefix = ['octavia-dashboard.'] -# openstackdocstheme options -repository_name = 'openstack/octavia-dashboard' -bug_project = '909' -bug_tag = 'docs' +# -- Options for LaTeX output ------------------------------------------------- -apidoc_output_dir = 'contributor/modules' -apidoc_module_dir = '../../octavia_dashboard' -apidoc_excluded_paths = [ - 'tests', - 'enabled', - 'locale', - 'static', - 'conf', - 'local_settings.d', - 'post_install.sh', - 'karma.conf.js' -] +# 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', + 'doc-octavia-dashboard.tex', + u'Octavia Dashboard Documentation', + u'OpenStack Octavia Team', + 'manual' +)] + +# 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 a12d7322..7041943b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,9 +4,7 @@ contain the root `toctree` directive. Welcome to octavia-dashboard's documentation! -======================================================== - -Contents: +============================================= .. toctree:: :maxdepth: 2 diff --git a/doc/source/reference.rst b/doc/source/reference.rst index 28e9fb4c..b27f2b02 100644 --- a/doc/source/reference.rst +++ b/doc/source/reference.rst @@ -2,15 +2,21 @@ Reference ========= -Indices and search ------------------- +.. only:: latex -.. toctree:: - :hidden: + Module Reference + ---------------- - contributor/modules/modules + .. toctree:: + :hidden: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + contributor/modules/modules +.. only:: html + + Indices and search + ------------------ + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/tox.ini b/tox.ini index fdfdb418..13b92fec 100644 --- a/tox.ini +++ b/tox.ini @@ -41,9 +41,19 @@ deps = -r{toxinidir}/requirements.txt -r{toxinidir}/doc/requirements.txt commands = - rm -rf doc/build + 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