From debff05779ad12bcbee4e009cdd28c4dc5d30444 Mon Sep 17 00:00:00 2001
From: matthew-fuller <mfuller@suse.com>
Date: Mon, 23 Sep 2019 14:09:01 -0700
Subject: [PATCH] PDF documentation build

This change provides the necessary modifications to enable
building of pdf documentation. The resources.py extension
required modification to:
  - prevent attributes from being rendered as stray \items
    outside of a list environment
  - prevent update policies from being rendered as stray
    \items outside of a list environment
  - remove the 'Note:' admonition around the 'Not implemented'
    message when it applies to a sub-property, such as a list.
    The admonition was not rendered as a list item, causing the
    build to fail due to an empty list.

Change-Id: Id4e533430600b5ff03fd63cdc09b9a00741b8e4e
---
 doc/source/conf.py                         | 23 ++++++++++------------
 doc/source/configuration/sample_config.rst | 12 +++++++++--
 doc/source/ext/resources.py                | 15 +++++++++++---
 tox.ini                                    |  9 +++++++++
 4 files changed, 41 insertions(+), 18 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 0532411440..2b75ee8a54 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -271,21 +271,10 @@ htmlhelp_basename = 'Heatdoc'
 
 # -- Options for LaTeX output -------------------------------------------------
 
-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.
-    # 'preamble': '',
-}
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual])
 latex_documents = [
-    ('index', 'Heat.tex', u'Heat Documentation',
+    ('index', 'doc-heat.tex', u'Heat Documentation',
      u'Heat Developers', 'manual'),
 ]
 
@@ -307,8 +296,16 @@ latex_documents = [
 # latex_appendices = []
 
 # If false, no module index is generated.
-# latex_domain_indices = True
+latex_domain_indices = False
 
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
+latex_elements = {
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+}
 
 # -- Options for manual page output -------------------------------------------
 
diff --git a/doc/source/configuration/sample_config.rst b/doc/source/configuration/sample_config.rst
index f572f48448..5e4b4fc1b6 100644
--- a/doc/source/configuration/sample_config.rst
+++ b/doc/source/configuration/sample_config.rst
@@ -7,6 +7,14 @@ auto-generated from heat when this documentation is built, so if you are
 having issues with an option, please compare your version of heat with the
 version of this documentation.
 
-The sample configuration can also be downloaded in `file form <../_static/heat.conf.sample>`_.
+.. only:: html
 
-.. literalinclude:: ../_static/heat.conf.sample
+   The sample configuration can also be downloaded in
+   `file form <../_static/heat.conf.sample>`_.
+
+   .. literalinclude:: ../_static/heat.conf.sample
+
+.. only:: latex
+
+   See the online version of this documentation for the full example config
+   file.
diff --git a/doc/source/ext/resources.py b/doc/source/ext/resources.py
index 32a0dc3ffd..50db470afb 100644
--- a/doc/source/ext/resources.py
+++ b/doc/source/ext/resources.py
@@ -245,7 +245,10 @@ resources:
         if not prop.implemented:
             para = nodes.line('', _('Not implemented.'))
             note = nodes.note('', para)
-            definition.append(note)
+            if sub_prop:
+                definition.append(para)
+            else:
+                definition.append(note)
             return
 
         if sub_prop and prop.type not in (properties.Schema.LIST,
@@ -351,11 +354,14 @@ resources:
         if not self.attrs_schemata:
             return
         section = self._section(parent, _('Attributes'), '%s-attrs')
+        definition_list = nodes.definition_list()
+        section.append(definition_list)
+
         for prop_key, prop in sorted(self.attrs_schemata.items()):
             if prop.support_status.status != support.HIDDEN:
                 description = prop.description
                 attr_section = self._prop_section(
-                    section, prop_key, '%s-attr-' + prop_key)
+                    definition_list, prop_key, '%s-attr-' + prop_key)
 
                 self._status_str(prop.support_status, attr_section)
 
@@ -367,9 +373,12 @@ resources:
         if not self.update_policy_schemata:
             return
         section = self._section(parent, _('update_policy'), '%s-updpolicy')
+        definition_list = nodes.definition_list()
+        section.append(definition_list)
+
         for _key, _prop in sorted(self.update_policy_schemata.items(),
                                   key=cmp_to_key(self.cmp_prop)):
-            self.contribute_property(section, _key, _prop)
+            self.contribute_property(definition_list, _key, _prop)
 
 
 class IntegrateResourcePages(ResourcePages):
diff --git a/tox.ini b/tox.ini
index 596d9f30be..b838cfe683 100644
--- a/tox.ini
+++ b/tox.ini
@@ -71,6 +71,15 @@ commands =
   rm -rf doc/build
   sphinx-build -W -b html doc/source doc/build/html
 
+[testenv:pdf-docs]
+basepython = python3
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  make
+commands =
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:api-ref]
 basepython = python3
 # This environment is called from CI scripts to test and publish