PDF theme & styling with openstackdocstheme

This commit applies theme and styling to PDF generation
using xelatex with customized styles.
In openstackdocstheme, style is defined in pdftheme.sty,
and conf.py makes use of the file as LaTeX package.
Also, some rst files are modified to add PDF directives
to adjust better UI in PDFs.

Not all documents are our targets in this commit but feel
free to add more here if anyone wants.

- Current applied styles with openstackdocstheme
 : Dedicated title without a blank page
 : Put a logo image into suitable place.
 : No chapter/section number
 : Light gray background for code blocks
 : Font definition is in openstackdocstheme not in conf.py

- rst modification
 : Table wrap adjustment (".. tabularcolumns::" directive)
 : Exclude "Search in this page" section (".. only:: html" directive)

Change-Id: I2782e0a1f0258a6016559b16c8967cc52f48f734
Depends-On: I423675ff79827966e789df70b0f970ac2a10da50
Implements: blueprint build-pdf-from-rst-guides
Co-Authored-By: Ian Y. Choi <ianyrchoi@gmail.com>

doc/arch-design/source/conf.py

@@ -30,6 +30,7 @@ import openstackdocstheme
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
 
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -38,7 +39,7 @@ import openstackdocstheme
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-# extensions = ['sphinx.ext.todo']
+# extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -207,27 +208,31 @@ htmlhelp_basename = 'arch-design'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+    
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/arch-design/source/index.rst

@@ -49,7 +49,9 @@ Glossary
 
    common/glossary.rst
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`

doc/common/cli-install-openstack-command-line-clients.rst

@@ -16,7 +16,9 @@ If you need to install the source package for the command-line package,
 the following table lists the software needed to run the
 command-line clients, and provides installation instructions as needed.
 
+.. tabularcolumns:: |p{0.2\textwidth}|p{0.75\textwidth}|
 .. list-table:: OpenStack command-line clients prerequisites
+   :class: longtable
    :header-rows: 1
    :widths: 20 80
 

doc/common/cli-overview.rst

@@ -42,6 +42,7 @@ Unless the unified OpenStack Client (**python-openstackclient**) is used,
 the following table lists the command-line client for each OpenStack
 service with its package name and description.
 
+.. tabularcolumns:: |p{0.2\textwidth}|l|l|p{0.35\textwidth}|
 .. list-table:: OpenStack services and clients
    :widths: 20 20 20 40
    :header-rows: 1

doc/ha-guide/source/conf.py

@@ -38,7 +38,7 @@ import openstackdocstheme
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+# extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -208,27 +208,31 @@ htmlhelp_basename = 'ha-guide'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/ha-guide/source/index.rst

@@ -19,6 +19,9 @@ This guide documents OpenStack Ocata, Newton, and Mitaka releases.
    `bug list <https://bugs.launchpad.net/openstack-manuals/>`_.
    Please help where you are able.
 
+Contents
+~~~~~~~~
+
 .. toctree::
    :maxdepth: 2
 

doc/ha-guide/source/networking-ha-l3.rst

@@ -13,6 +13,7 @@ and `Open vSwitch: High availability using VRRP
 To enable high availability for configured routers, edit the
 :file:`/etc/neutron/neutron.conf` file to set the following values:
 
+.. tabularcolumns:: |l|l|L|
 .. list-table:: /etc/neutron/neutron.conf parameters for high availability
    :widths: 15 10 30
    :header-rows: 1

doc/image-guide/source/conf.py

@@ -38,7 +38,7 @@ import openstackdocstheme
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-# extensions = ['sphinx.ext.todo']
+# extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -208,27 +208,31 @@ htmlhelp_basename = 'image-guide'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/image-guide/source/index.rst

@@ -40,7 +40,9 @@ Glossary
 
    common/glossary.rst
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`

doc/image-guide/source/openstack-images.rst

@@ -358,6 +358,7 @@ For information about the libvirt images in OpenStack, see
 `The life of an OpenStack libvirt image from Pádraig Brady
 <http://www.pixelbeat.org/docs/openstack_libvirt_images/>`_.
 
+.. tabularcolumns:: |l|p{0.4\textwidth}|
 .. list-table:: Image cache management configuration options
    :widths: 50 50
    :header-rows: 1

doc/install-guide-debconf/source/conf.py

@@ -221,27 +221,31 @@ htmlhelp_basename = 'install-guide'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/install-guide-debconf/source/index.rst

@@ -62,7 +62,9 @@ Glossary
 
    common/glossary.rst
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`

doc/install-guide/source/conf.py

@@ -221,27 +221,31 @@ htmlhelp_basename = 'install-guide'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/install-guide/source/index.rst

@@ -146,7 +146,9 @@ Glossary
 
    common/glossary.rst
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`

doc/networking-guide/source/conf.py

@@ -207,27 +207,31 @@ htmlhelp_basename = 'networking-guide'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/networking-guide/source/index.rst

@@ -45,7 +45,9 @@ Glossary
 
    common/glossary
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`

doc/ops-guide/source/conf.py

@@ -208,27 +208,31 @@ htmlhelp_basename = 'ops-guide'
 html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/ops-guide/source/index.rst

@@ -70,7 +70,9 @@ Glossary
 
    common/glossary.rst
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`

doc/user-guide/source/cli-nova-launch-instance-from-volume.rst

@@ -7,6 +7,7 @@ You can boot instances from a volume instead of an image.
 To complete these tasks, use these parameters on the
 :command:`openstack server create` command:
 
+.. tabularcolumns:: |p{0.3\textwidth}|p{0.25\textwidth}|p{0.4\textwidth}|
 .. list-table::
    :header-rows: 1
    :widths: 30 15 30

doc/user-guide/source/cli-swift-large-object-creation.rst

@@ -275,6 +275,7 @@ Comparison of static and dynamic large objects
 While static and dynamic objects have similar behavior, this table describes
 their differences:
 
+.. tabularcolumns:: |p{0.2\textwidth}|p{0.35\textwidth}|p{0.35\textwidth}|
 .. list-table::
    :header-rows: 1
    :widths: 20 25 25

doc/user-guide/source/conf.py

@@ -23,7 +23,6 @@
 import os
 # import sys
 
-
 import openstackdocstheme
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -39,7 +38,7 @@ import openstackdocstheme
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+# extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -213,27 +212,31 @@ html_copy_source = False
 linkcheck_ignore = [r'https://build.opensuse.org']
 
 # -- Options for LaTeX output ---------------------------------------------
+pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+openstack_logo = openstackdocstheme.get_openstack_logo_path()
+
+latex_custom_template = r"""
+\newcommand{\openstacklogo}{%s}
+\usepackage{%s}
+""" % (openstack_logo, pdf_theme_path)
 
 latex_engine = 'xelatex'
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    'papersize': 'a4paper',
-
-    # set font (TODO: different fonts for translated PDF document builds)
-    'fontenc': '\\usepackage{fontspec}',
-    'fontpkg': '''\
-\defaultfontfeatures{Scale=MatchLowercase}
-\setmainfont{Liberation Serif}
-\setsansfont{Liberation Sans}
-\setmonofont[SmallCapsFont={Liberation Mono}]{Liberation Mono}
-''',
 
     # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    'pointsize': '11pt',
+    
+    #Default figure align
+    'figure_align': 'H',
+
+    # Not to generate blank page after chapter
+    'classoptions': ',openany',
 
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': latex_custom_template,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/user-guide/source/index.rst

@@ -43,7 +43,9 @@ Glossary
 
    common/glossary.rst
 
-Search
+.. only:: html
-~~~~~~
 
-* :ref:`search`
+   Search
+   ~~~~~~
+
+   * :ref:`search`