From dc68cc8e03bbddb31d1fc9de0e0a38b484cf075e Mon Sep 17 00:00:00 2001 From: SeongSoo Cho Date: Thu, 2 Feb 2017 02:33:44 +0900 Subject: [PATCH] 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 --- doc/arch-design/source/conf.py | 31 +++++++++++-------- doc/arch-design/source/index.rst | 8 +++-- ...install-openstack-command-line-clients.rst | 2 ++ doc/common/cli-overview.rst | 1 + doc/ha-guide/source/conf.py | 30 ++++++++++-------- doc/ha-guide/source/index.rst | 3 ++ doc/ha-guide/source/networking-ha-l3.rst | 1 + doc/image-guide/source/conf.py | 30 ++++++++++-------- doc/image-guide/source/index.rst | 8 +++-- doc/image-guide/source/openstack-images.rst | 1 + doc/install-guide-debconf/source/conf.py | 28 ++++++++++------- doc/install-guide-debconf/source/index.rst | 8 +++-- doc/install-guide/source/conf.py | 28 ++++++++++------- doc/install-guide/source/index.rst | 8 +++-- doc/networking-guide/source/conf.py | 28 ++++++++++------- doc/networking-guide/source/index.rst | 8 +++-- doc/ops-guide/source/conf.py | 28 ++++++++++------- doc/ops-guide/source/index.rst | 8 +++-- .../cli-nova-launch-instance-from-volume.rst | 1 + .../cli-swift-large-object-creation.rst | 1 + doc/user-guide/source/conf.py | 31 ++++++++++--------- doc/user-guide/source/index.rst | 8 +++-- 22 files changed, 178 insertions(+), 122 deletions(-) diff --git a/doc/arch-design/source/conf.py b/doc/arch-design/source/conf.py index 4a8a677cb2..13e0440466 100644 --- a/doc/arch-design/source/conf.py +++ b/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', - - # 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 diff --git a/doc/arch-design/source/index.rst b/doc/arch-design/source/index.rst index 7a4e473404..b185ebc173 100644 --- a/doc/arch-design/source/index.rst +++ b/doc/arch-design/source/index.rst @@ -49,7 +49,9 @@ Glossary common/glossary.rst -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search` diff --git a/doc/common/cli-install-openstack-command-line-clients.rst b/doc/common/cli-install-openstack-command-line-clients.rst index 42b85743dc..cb6eff7543 100644 --- a/doc/common/cli-install-openstack-command-line-clients.rst +++ b/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 diff --git a/doc/common/cli-overview.rst b/doc/common/cli-overview.rst index 6799e7a839..7a38e308cd 100644 --- a/doc/common/cli-overview.rst +++ b/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 diff --git a/doc/ha-guide/source/conf.py b/doc/ha-guide/source/conf.py index a1808bb000..12a8c56ad6 100644 --- a/doc/ha-guide/source/conf.py +++ b/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', - - # 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 diff --git a/doc/ha-guide/source/index.rst b/doc/ha-guide/source/index.rst index b10a54ae11..650b1d1afd 100644 --- a/doc/ha-guide/source/index.rst +++ b/doc/ha-guide/source/index.rst @@ -19,6 +19,9 @@ This guide documents OpenStack Ocata, Newton, and Mitaka releases. `bug list `_. Please help where you are able. +Contents +~~~~~~~~ + .. toctree:: :maxdepth: 2 diff --git a/doc/ha-guide/source/networking-ha-l3.rst b/doc/ha-guide/source/networking-ha-l3.rst index 11eeccff8d..231b262b72 100644 --- a/doc/ha-guide/source/networking-ha-l3.rst +++ b/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 diff --git a/doc/image-guide/source/conf.py b/doc/image-guide/source/conf.py index 6990f14b06..d73ca5ea94 100644 --- a/doc/image-guide/source/conf.py +++ b/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', - - # 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 diff --git a/doc/image-guide/source/index.rst b/doc/image-guide/source/index.rst index e5fc7913aa..20131b65c8 100644 --- a/doc/image-guide/source/index.rst +++ b/doc/image-guide/source/index.rst @@ -40,7 +40,9 @@ Glossary common/glossary.rst -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search` diff --git a/doc/image-guide/source/openstack-images.rst b/doc/image-guide/source/openstack-images.rst index 34b0156405..b86cac16c0 100644 --- a/doc/image-guide/source/openstack-images.rst +++ b/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 `_. +.. tabularcolumns:: |l|p{0.4\textwidth}| .. list-table:: Image cache management configuration options :widths: 50 50 :header-rows: 1 diff --git a/doc/install-guide-debconf/source/conf.py b/doc/install-guide-debconf/source/conf.py index 161b706b05..3995c3707d 100644 --- a/doc/install-guide-debconf/source/conf.py +++ b/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', - - # 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 diff --git a/doc/install-guide-debconf/source/index.rst b/doc/install-guide-debconf/source/index.rst index 4de6851d80..80158593a5 100644 --- a/doc/install-guide-debconf/source/index.rst +++ b/doc/install-guide-debconf/source/index.rst @@ -62,7 +62,9 @@ Glossary common/glossary.rst -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search` diff --git a/doc/install-guide/source/conf.py b/doc/install-guide/source/conf.py index 836f90fec7..a230bedaa4 100644 --- a/doc/install-guide/source/conf.py +++ b/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', - - # 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 diff --git a/doc/install-guide/source/index.rst b/doc/install-guide/source/index.rst index b7cae7c599..41833bf388 100644 --- a/doc/install-guide/source/index.rst +++ b/doc/install-guide/source/index.rst @@ -146,7 +146,9 @@ Glossary common/glossary.rst -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search` diff --git a/doc/networking-guide/source/conf.py b/doc/networking-guide/source/conf.py index af9f58c2f4..e400cdcc1b 100644 --- a/doc/networking-guide/source/conf.py +++ b/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', - - # 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 diff --git a/doc/networking-guide/source/index.rst b/doc/networking-guide/source/index.rst index e63e78192d..7e7157960f 100644 --- a/doc/networking-guide/source/index.rst +++ b/doc/networking-guide/source/index.rst @@ -45,7 +45,9 @@ Glossary common/glossary -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search` diff --git a/doc/ops-guide/source/conf.py b/doc/ops-guide/source/conf.py index 9ad35d7858..643d139a99 100644 --- a/doc/ops-guide/source/conf.py +++ b/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', - - # 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 diff --git a/doc/ops-guide/source/index.rst b/doc/ops-guide/source/index.rst index 7a77327568..4e244a9532 100644 --- a/doc/ops-guide/source/index.rst +++ b/doc/ops-guide/source/index.rst @@ -70,7 +70,9 @@ Glossary common/glossary.rst -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search` diff --git a/doc/user-guide/source/cli-nova-launch-instance-from-volume.rst b/doc/user-guide/source/cli-nova-launch-instance-from-volume.rst index a97de7a97d..7cebf87746 100644 --- a/doc/user-guide/source/cli-nova-launch-instance-from-volume.rst +++ b/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 diff --git a/doc/user-guide/source/cli-swift-large-object-creation.rst b/doc/user-guide/source/cli-swift-large-object-creation.rst index 3bf105a9bf..5474b61c07 100644 --- a/doc/user-guide/source/cli-swift-large-object-creation.rst +++ b/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 diff --git a/doc/user-guide/source/conf.py b/doc/user-guide/source/conf.py index ea03548fc2..23420a7af3 100644 --- a/doc/user-guide/source/conf.py +++ b/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', - - # 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 diff --git a/doc/user-guide/source/index.rst b/doc/user-guide/source/index.rst index eff895e22d..a14eca3272 100644 --- a/doc/user-guide/source/index.rst +++ b/doc/user-guide/source/index.rst @@ -43,7 +43,9 @@ Glossary common/glossary.rst -Search -~~~~~~ +.. only:: html -* :ref:`search` + Search + ~~~~~~ + + * :ref:`search`