From b9efbaa2284c420ebf9a3661c137b55f63726351 Mon Sep 17 00:00:00 2001 From: Anthony Keenan Date: Tue, 24 Jul 2018 10:05:57 +0100 Subject: [PATCH] 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 | 1 + docs/ext/conditional_toctree.py | 37 ++++++++++++++ docs/source/building-container-images.rst | 2 +- docs/source/conf.py | 6 ++- docs/source/contributing-index.rst | 17 +++++++ docs/source/contributing.rst | 14 ++---- docs/source/getting-set-up.rst | 2 +- docs/source/index.rst | 61 ++++++++++++----------- docs/source/release-process-index.rst | 12 ----- 9 files changed, 98 insertions(+), 54 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/ext/conditional_toctree.py create mode 100644 docs/source/contributing-index.rst delete mode 100644 docs/source/release-process-index.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..0d20b6487c --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +*.pyc diff --git a/docs/ext/conditional_toctree.py b/docs/ext/conditional_toctree.py new file mode 100644 index 0000000000..3b1e65d4cd --- /dev/null +++ b/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 [] diff --git a/docs/source/building-container-images.rst b/docs/source/building-container-images.rst index 58e02b3580..21df0e4ffb 100644 --- a/docs/source/building-container-images.rst +++ b/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 `_ for details. diff --git a/docs/source/conf.py b/docs/source/conf.py index e604d66e91..d7e1aa3a2b 100644 --- a/docs/source/conf.py +++ b/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', } + diff --git a/docs/source/contributing-index.rst b/docs/source/contributing-index.rst new file mode 100644 index 0000000000..1187c1af22 --- /dev/null +++ b/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 `_. 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 \ No newline at end of file diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 9b8e885de9..6e4516dd05 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -1,14 +1,9 @@ -Contributing -============ - -Corda is an open-source project and contributions are welcome. Our contributing philosophy is described in -`CONTRIBUTING.md `_. This guide explains the mechanics -of contributing to Corda. - -.. contents:: +How to contribute +================= 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 `_ 2. Clone the fork to your local machine -3. Make the changes, in accordance with the :doc:`code style guide ` +3. Build Corda by following the instructions :doc:`here ` +4. Make the changes, in accordance with the :doc:`code style guide ` Extending the flow state machine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/getting-set-up.rst b/docs/source/getting-set-up.rst index a96dfbb0ab..1ad1a71465 100644 --- a/docs/source/getting-set-up.rst +++ b/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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 04b65a85d9..a909055626 100644 --- a/docs/source/index.rst +++ b/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:: - :caption: Other documentation +.. conditional-toctree:: + :caption: Contents + :maxdepth: 2 + :if_tag: pdfmode - deterministic-modules.rst - release-notes.rst - changelog.rst + deterministic-modules.rst + release-notes.rst + changelog.rst -.. only:: htmlmode +.. conditional-toctree:: + :caption: Design docs + :maxdepth: 2 + :if_tag: htmlmode - .. toctree:: - :caption: Design docs - :maxdepth: 2 + design/design-review-process.md + design/certificate-hierarchies/design.md + 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 - design/certificate-hierarchies/design.md - 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 - - .. 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 +.. conditional-toctree:: + :caption: Participate + :maxdepth: 2 + :if_tag: htmlmode + + contributing-index.rst + corda-repo-layout.rst + deterministic-modules.rst + release-notes + changelog diff --git a/docs/source/release-process-index.rst b/docs/source/release-process-index.rst deleted file mode 100644 index 9ef0c82347..0000000000 --- a/docs/source/release-process-index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Release process -=============== - -.. toctree:: - :maxdepth: 1 - - release-notes - changelog - contributing - codestyle - testing - api-scanner \ No newline at end of file