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,11 +30,10 @@ 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
-
-    .. toctree::
+.. conditional-toctree::
    :caption: Contents
    :maxdepth: 2
+   :if_tag: pdfmode
 
    release-notes.rst
    key-concepts.rst
@@ -54,11 +53,10 @@ application development please continue to refer to `the main project documentat
    json.rst
    troubleshooting.rst
 
-.. only:: htmlmode
-
-    .. toctree::
+.. conditional-toctree::
    :caption: Corda Enterprise
    :maxdepth: 1
+   :if_tag: htmlmode
 
    release-notes.rst
    version-compatibility.rst
@@ -69,9 +67,10 @@ application development please continue to refer to `the main project documentat
    sizing-and-performance
    running-a-notary-cluster/toctree
 
-    .. toctree::
+.. conditional-toctree::
    :caption: Development
    :maxdepth: 1
+   :if_tag: htmlmode
 
    quickstart-index.rst
    key-concepts.rst
@@ -84,12 +83,11 @@ application development please continue to refer to `the main project documentat
    json.rst
    troubleshooting.rst
 
-    .. toctree::
+.. conditional-toctree::
    :caption: Operations
    :maxdepth: 2
+   :if_tag: htmlmode
 
    corda-nodes-index.rst
    corda-networks-index.rst
-       azure-vm.rst
-       aws-vm.rst
    certificate-revocation