CORDA-1585 - Tidy up participate docs + pdf toctree backport (#3674)

* Fix TOC for HTML and PDF (Backport from Enterprise docs)

* Tidy up participate section

* Address review comments

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/building-container-images.rst

@@ -1,5 +1,5 @@
 =========================
-Building Container Images
+Building container images
 =========================
 
 To build a container image of Corda you can use the Jib gradle tasks. See the `documentation of the Jib gradle plugin <https://github.com/GoogleContainerTools/jib/tree/master/jib-gradle-plugin>`_ for details.

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 Developer Documentation', u'R3')]
@@ -274,3 +277,4 @@ latex_elements = {
 
     'extraclassoptions' : 'openany',
 }
+

docs/source/contributing-index.rst

@@ -0,0 +1,17 @@
+Contributing
+============
+
+Corda is an open-source project and contributions are welcome. Our contributing philosophy is described in
+`CONTRIBUTING.md <https://github.com/corda/corda/blob/master/CONTRIBUTING.md>`_. This guide explains the mechanics
+of contributing to Corda.
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   building-corda
+   testing
+   codestyle
+   building-the-docs
+   api-scanner
+   contributing-flow-state-machines

docs/source/contributing.rst

@@ -1,14 +1,9 @@
-Contributing
+How to contribute
-============
+=================
-
-Corda is an open-source project and contributions are welcome. Our contributing philosophy is described in 
-`CONTRIBUTING.md <https://github.com/corda/corda/blob/master/CONTRIBUTING.md>`_. This guide explains the mechanics 
-of contributing to Corda.
-
-.. contents::
 
 Identifying an area to contribute
 ---------------------------------
+
 There are several ways to identify an area where you can contribute to Corda:
 
 * Browse issues labelled as ``good first issue`` in the
@@ -26,7 +21,8 @@ Making the required changes
 
 1. Create a fork of the master branch of the `Corda repo <https://github.com/corda/corda>`_
 2. Clone the fork to your local machine
-3. Make the changes, in accordance with the :doc:`code style guide </codestyle>`
+3. Build Corda by following the instructions :doc:`here </building-corda>`
+4. Make the changes, in accordance with the :doc:`code style guide </codestyle>`
 
 Extending the flow state machine
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/source/getting-set-up.rst

@@ -100,7 +100,7 @@ IntelliJ
 .. _deb-ubuntu-label:
 
 Debian/Ubuntu
-------
+-------------
 
 .. warning:: If you are using a Mac or a Windows machine, please follow the :ref:`mac-label` or :ref:`windows-label` instructions instead.
 

docs/source/index.rst

@@ -53,40 +53,41 @@ We look forward to seeing what you can do with Corda!
    azure-vm.rst
    aws-vm.rst
    loadtesting.rst
+   building-container-images.rst
 
 .. Documentation is not included in the pdf unless it is included in a toctree somewhere
-.. only:: pdfmode
 
-   .. toctree::
+.. conditional-toctree::
-      :caption: Other documentation
+   :caption: Contents
+   :maxdepth: 2
+   :if_tag: pdfmode
 
-      deterministic-modules.rst
+   deterministic-modules.rst
-      release-notes.rst
+   release-notes.rst
-      changelog.rst
+   changelog.rst
 
-.. only:: htmlmode
+.. conditional-toctree::
+   :caption: Design docs
+   :maxdepth: 2
+   :if_tag: htmlmode
 
-   .. toctree::
+   design/design-review-process.md
-      :caption: Design docs
+   design/certificate-hierarchies/design.md
-      :maxdepth: 2
+   design/failure-detection-master-election/design.md
+   design/float/design.md
+   design/hadr/design.md
+   design/kafka-notary/design.md
+   design/monitoring-management/design.md
+   design/sgx-integration/design.md
+   design/sgx-infrastructure/design.md
 
-      design/design-review-process.md
+.. conditional-toctree::
-      design/certificate-hierarchies/design.md
+   :caption: Participate
-      design/failure-detection-master-election/design.md
+   :maxdepth: 2
-      design/float/design.md
+   :if_tag: htmlmode
-      design/hadr/design.md
+   
-      design/kafka-notary/design.md
+   contributing-index.rst
-      design/monitoring-management/design.md
+   corda-repo-layout.rst
-      design/sgx-integration/design.md
+   deterministic-modules.rst
-      design/sgx-infrastructure/design.md
+   release-notes
-
+   changelog
-   .. toctree::
-      :caption: Participate
-      :maxdepth: 2
-
-      building-corda.rst
-      release-process-index.rst
-      corda-repo-layout.rst
-      deterministic-modules.rst
-      building-the-docs.rst
-      building-container-images.rst

docs/source/release-process-index.rst

@@ -1,12 +0,0 @@
-Release process
-===============
-
-.. toctree::
-   :maxdepth: 1
-
-   release-notes
-   changelog
-   contributing
-   codestyle
-   testing
-   api-scanner