ENT-1955 - Fix TOC for HTML and PDF (#1244)

docs/.gitignore

@@ -0,0 +1 @@
+*.pyc

docs/ext/conditional_toctree.py

@@ -0,0 +1,37 @@
+import re
+from docutils.parsers.rst import directives
+from sphinx.directives.other import TocTree
+
+def setup(app):
+    app.add_directive('conditional-toctree', ConditionalTocTree)
+    ConditionalTocTree.defined_tags = app.tags.tags.keys()
+    return {'version': '1.0.0'}
+
+def tag(argument):
+    return directives.choice(argument, ('htmlmode', 'pdfmode'))
+
+class ConditionalTocTree(TocTree):
+
+    defined_tags = []
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'maxdepth': int,
+        'name': directives.unchanged,
+        'caption': directives.unchanged_required,
+        'glob': directives.flag,
+        'hidden': directives.flag,
+        'includehidden': directives.flag,
+        'titlesonly': directives.flag,
+        'reversed': directives.flag,
+        'if_tag': tag,
+    }
+
+    def run(self):
+        if_tag = self.options.get('if_tag')
+        if if_tag in self.defined_tags:
+            return TocTree.run(self)
+        else:
+            return []

docs/source/conf.py

@@ -13,6 +13,9 @@
 # serve to show the default.
 
 import sphinx_rtd_theme
+import sys, os
+
+sys.path.append(os.path.abspath('../ext/'))
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -25,7 +28,7 @@ import sphinx_rtd_theme
 # needs_sphinx = '1.0'
 
 # m2r is a Markdown to RST converter, as our design docs use Markdown.
-extensions = ['rst2pdf.pdfbuilder', 'm2r']
+extensions = ['rst2pdf.pdfbuilder', 'm2r', 'conditional_toctree']
 
 # PDF configuration
 pdf_documents = [('index', u'corda-developer-site', u'Corda Enterprise Documentation', u'R3')]
@@ -275,3 +278,4 @@ latex_elements = {
 
     'extraclassoptions' : 'openany',
 }
+

docs/source/index.rst

@@ -30,66 +30,64 @@ application development please continue to refer to `the main project documentat
 
 .. Documentation is not included in the pdf unless it is included in a toctree somewhere
 
-.. only:: pdfmode
+.. conditional-toctree::
+   :caption: Contents
+   :maxdepth: 2
+   :if_tag: pdfmode
 
-    .. toctree::
-       :caption: Contents
-       :maxdepth: 2
+   release-notes.rst
+   key-concepts.rst
+   quickstart-index.rst
+   tutorials-index.rst
+   building-a-cordapp-index.rst
+   component-library-index.rst
+   corda-nodes-index.rst
+   corda-networks-index.rst
+   tools-index.rst
+   corda-firewall
+   database-management
+   hot-cold-deployment
+   running-a-notary-cluster/toctree
+   certificate-revocation
+   node-internals-index.rst
+   json.rst
+   troubleshooting.rst
 
-       release-notes.rst
-       key-concepts.rst
-       quickstart-index.rst
-       tutorials-index.rst
-       building-a-cordapp-index.rst
-       component-library-index.rst
-       corda-nodes-index.rst
-       corda-networks-index.rst
-       tools-index.rst
-       corda-firewall
-       database-management
-       hot-cold-deployment
-       running-a-notary-cluster/toctree
-       certificate-revocation
-       node-internals-index.rst
-       json.rst
-       troubleshooting.rst
+.. conditional-toctree::
+   :caption: Corda Enterprise
+   :maxdepth: 1
+   :if_tag: htmlmode
 
-.. only:: htmlmode
+   release-notes.rst
+   version-compatibility.rst
+   platform-support-matrix.rst
+   hot-cold-deployment
+   database-management
+   corda-firewall
+   sizing-and-performance
+   running-a-notary-cluster/toctree
 
-    .. toctree::
-       :caption: Corda Enterprise
-       :maxdepth: 1
+.. conditional-toctree::
+   :caption: Development
+   :maxdepth: 1
+   :if_tag: htmlmode
 
-       release-notes.rst
-       version-compatibility.rst
-       platform-support-matrix.rst
-       hot-cold-deployment
-       database-management
-       corda-firewall
-       sizing-and-performance
-       running-a-notary-cluster/toctree
+   quickstart-index.rst
+   key-concepts.rst
+   building-a-cordapp-index.rst
+   tutorials-index.rst
+   tools-index.rst
+   node-internals-index.rst
+   component-library-index.rst
+   serialization-index.rst
+   json.rst
+   troubleshooting.rst
 
-    .. toctree::
-       :caption: Development
-       :maxdepth: 1
+.. conditional-toctree::
+   :caption: Operations
+   :maxdepth: 2
+   :if_tag: htmlmode
 
-       quickstart-index.rst
-       key-concepts.rst
-       building-a-cordapp-index.rst
-       tutorials-index.rst
-       tools-index.rst
-       node-internals-index.rst
-       component-library-index.rst
-       serialization-index.rst
-       json.rst
-       troubleshooting.rst
-
-    .. toctree::
-       :caption: Operations
-       :maxdepth: 2
-
-       corda-nodes-index.rst
-       corda-networks-index.rst
-       azure-vm.rst
-       aws-vm.rst
-       certificate-revocation
+   corda-nodes-index.rst
+   corda-networks-index.rst
+   certificate-revocation