From 76cbd2dbbb131224e73a4b7c4019c378d2bbaf20 Mon Sep 17 00:00:00 2001
From: Kaifeng Wang <kaifeng.w@gmail.com>
Date: Fri, 6 Sep 2019 15:25:44 +0800
Subject: [PATCH] Build pdf doc

The is one of community goals that each project could produce a
single PDF file. The pdf should be in the output of openstack-tox-docs
job.

TeX packages are required to build PDF locally, following is recommended:

* inkscape
* texlive-latex-base
* texlive-latex-extra
* texlive-fonts-recommended

More about the goal:
https://governance.openstack.org/tc/goals/train/pdf-doc-generation.html
https://etherpad.openstack.org/p/train-pdf-support-goal
https://etherpad.openstack.org/p/pdf-goal-train-common-problems

Change-Id: I784be3f2462184ce951cb27e68e578f8befaa580
---
 doc/source/conf.py                 | 15 +++++++--------
 doc/source/configuration/index.rst | 11 +++++++++--
 lower-constraints.txt              |  3 ++-
 test-requirements.txt              |  3 ++-
 tox.ini                            |  8 ++++++++
 5 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index f08531854..e0917fbee 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -7,6 +7,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
+              'sphinxcontrib.rsvgconverter',
               'oslo_policy.sphinxext',
               'oslo_policy.sphinxpolicygen',
               'oslo_config.sphinxext',
@@ -19,9 +20,7 @@ except ImportError:
     openstackdocstheme = None
 
 repository_name = 'openstack/ironic-inspector'
-bug_project = 'ironic-inspector'
-bug_tag = ''
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
+use_storyboard = True
 
 wsme_protocols = ['restjson']
 
@@ -39,8 +38,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Ironic Inspector'
-copyright = u'OpenStack Foundation'
+copyright = u'OpenStack Developers'
 
 config_generator_config_file = '../../tools/config-generator.conf'
 sample_config_basename = '_static/ironic-inspector'
@@ -92,8 +90,9 @@ else:
 #html_static_path = ['_static']
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
+htmlhelp_basename = 'ironic-inspectordoc'
 
+latex_use_xindy = False
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
@@ -101,8 +100,8 @@ htmlhelp_basename = '%sdoc' % project
 latex_documents = [
     (
         'index',
-        '%s.tex' % project,
-        u'%s Documentation' % project,
+        'doc-ironic-inspector.tex',
+        u'Ironic Inspector Documentation',
         u'OpenStack Foundation',
         'manual'
     ),
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index c9fad8ef5..87d46decf 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -8,8 +8,15 @@ file. The overview of configuration file options follow.
   :maxdepth: 1
 
   Ironic Inspector Configuration Options <ironic-inspector>
-  Sample Ironic Inspector Configuration <sample-config>
   Policies <policy>
-  Sample policy file <sample-policy>
 
+.. only:: html
 
+   Sample files
+   ------------
+
+   .. toctree::
+      :maxdepth: 1
+
+      Sample Ironic Inspector Configuration <sample-config>
+      Sample policy file <sample-policy>
diff --git a/lower-constraints.txt b/lower-constraints.txt
index 144e333d5..471614af5 100644
--- a/lower-constraints.txt
+++ b/lower-constraints.txt
@@ -55,7 +55,7 @@ msgpack==0.5.6
 munch==2.2.0
 netaddr==0.7.18
 netifaces==0.10.6
-openstackdocstheme==1.18.1
+openstackdocstheme==1.20.0
 openstacksdk==0.30.0
 os-api-ref==1.4.0
 os-client-config==1.29.0
@@ -111,6 +111,7 @@ simplejson==3.13.2
 six==1.10.0
 snowballstemmer==1.2.1
 Sphinx==1.6.2
+sphinxcontrib-svg2pdfconverter==0.1.0
 sphinxcontrib-websupport==1.0.1
 sqlalchemy-migrate==0.11.0
 SQLAlchemy==1.0.10
diff --git a/test-requirements.txt b/test-requirements.txt
index 4af9b6252..a15e2776b 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -9,7 +9,8 @@ hacking>=1.0.0,<1.2.0 # Apache-2.0
 mock>=3.0.0 # BSD
 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;python_version>='3.4' # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+openstackdocstheme>=1.20.0 # Apache-2.0
 os-api-ref>=1.4.0 # Apache-2.0
 stestr>=1.0.0 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index 6e77f90de..f8ee7d71a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -97,6 +97,14 @@ deps = -r{toxinidir}/test-requirements.txt
 commands =
   python setup.py build_sphinx
 
+[testenv:pdf-docs]
+basepython = python3
+whitelist_externals = make
+deps = {[testenv:docs]deps}
+commands =
+  sphinx-build -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:lower-constraints]
 basepython = python3
 deps =