openstack
/
openstack-manuals
Code Issues Proposed changes

PDF theme & styling with openstackdocstheme

Browse Source 
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>
changes/26/427826/27
SeongSoo Cho 6 years ago committed by Ian Y. Choi
parent 240a84d8f4
commit dc68cc8e03
22 changed files with 178 additions and 122 deletions
Show Stats Download Patch File Download Diff File

31
doc/arch-design/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/arch-design/source/index.rst
Unescape View File

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

2
doc/common/cli-install-openstack-command-line-clients.rst
Unescape View File

@ -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

1
doc/common/cli-overview.rst
Unescape View File

@ -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

30
doc/ha-guide/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

3
doc/ha-guide/source/index.rst
Unescape View File

@ -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

1
doc/ha-guide/source/networking-ha-l3.rst
Unescape View File

@ -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

30
doc/image-guide/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/image-guide/source/index.rst
Unescape View File

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

1
doc/image-guide/source/openstack-images.rst
Unescape View File

@ -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

28
doc/install-guide-debconf/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/install-guide-debconf/source/index.rst
Unescape View File

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

28
doc/install-guide/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/install-guide/source/index.rst
Unescape View File

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

28
doc/networking-guide/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/networking-guide/source/index.rst
Unescape View File

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

28
doc/ops-guide/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/ops-guide/source/index.rst
Unescape View File

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

1
doc/user-guide/source/cli-nova-launch-instance-from-volume.rst
Unescape View File

@ -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

1
doc/user-guide/source/cli-swift-large-object-creation.rst
Unescape View File

@ -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

31
doc/user-guide/source/conf.py
Unescape View File

@ -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',
# 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}
''',
'papersize': 'a4paper',
# 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

8
doc/user-guide/source/index.rst
Unescape View File

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

Write Preview
Loading…
Cancel
Save