Rebuild user documentation

This commit is contained in:
Ross Nicoll
2016-04-28 17:15:56 +01:00
parent c13b5f247e
commit 31da33425e
10 changed files with 155 additions and 42 deletions

View File

@ -0,0 +1,54 @@
Building the documentation
==========================
The documentation is under the ``docs`` folder, and is written in reStructuredText format. Documentation in HTML format
is pre-generated, as well as code documentation, and this can be done automatically via a provided script.
Requirements
------------
To build the documentation, you will need:
* GNU Make
* Python and pip (tested with Python 2.7.10)
* Dokka: https://github.com/Kotlin/dokka
* Sphinx: http://www.sphinx-doc.org/
* sphinx_rtd_theme: https://github.com/snide/sphinx_rtd_theme
The Dokka JAR file needs to be placed under the ``lib`` directory within the ``r3prototyping`` directory, in order for the
script to find it, as in:
.. sourcecode:: shell
r3prototyping/lib/dokka.jar
Note that to install under OS X El Capitan, you will need to tell pip to install under ``/usr/local``, which can be
done by specifying the installation target on the command line:
.. sourcecode:: shell
sudo -H pip install --install-option '--install-data=/usr/local' Sphinx
sudo -H pip install --install-option '--install-data=/usr/local' sphinx_rtd_theme
Build
-----
Once the requirements are installed, you can automatically build the HTML format user documentation and the API
documentation by running the following script:
.. sourcecode:: shell
scripts/generate-docsite.sh
Alternatively you can build non-HTML formats from the ``docs`` folder. Change directory to the folder and then run the
following to see a list of all available formats:
.. sourcecode:: shell
make
For example to produce the documentation in HTML format:
.. sourcecode:: shell
make html

View File

@ -47,4 +47,5 @@ Read on to learn:
visualiser
codestyle
building-the-docs

View File

@ -94,4 +94,29 @@ sit around waiting for messages to be delivered. Handlers will then be invoked o
more difficult style of programming that can be used to increase the realism of the unit tests by ensuring multiple
nodes run in parallel, just as they would on a real network spread over multiple machines.
Network Map Service
-------------------
Supporting the messaging layer is a network map service, which is responsible for tracking public nodes on the network.
Nodes have an internal component, the network map cache, which contains a copy of the network map. When a node starts up
its cache fetches a copy of the full network map, and requests to be notified of changes. The node then registers itself
with the network map service, and the service notifies subscribers that a new node has joined the network. Nodes do not
automatically deregister themselves, so far (for example) nodes going offline briefly for maintenance
Nodes submit signed changes to the map service, which then forwards them on to nodes which have requested to be notified
of changes. This process achieves basic consensus of the overall network map, although currently it has no formal
process for identifying or recovering from issues such as network outages. Later versions are planned to address this.
Registration change notifications contain a serial number, which indicates their relative ordering, similar to the
serial number on DNS records. These numbers must increase with each change, but are not expected to be sequential.
Changes are then signed by the party whom the node represents to confirm the association between party and node.
The change, signature and public key are then sent to the network map service, which verifies the signature and then
updates the network map accordingly.
The network map cache currently supports:
* Looking up nodes by service
* Looking up node for a party
* Suggesting a node providing a specific service, based on suitability for a contract and parties, for example suggesting
an appropriate interest rates oracle for a interest rate swap contract. Currently no recommendation logic is in place
(the code simply picks the first registered node that supports the required service), however.

View File

@ -31,8 +31,7 @@
<link rel="top" title="R3 Prototyping latest documentation" href="index.html"/>
<link rel="next" title="Protocol state machines" href="protocol-state-machines.html"/>
<link rel="prev" title="Writing a contract" href="tutorial.html"/>
<link rel="prev" title="Code style guide" href="codestyle.html"/>
<script src="_static/js/modernizr.min.js"></script>
@ -96,20 +95,20 @@
<li class="toctree-l1"><a class="reference internal" href="irs.html">The Interest Rate Swap Contract</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Writing a contract</a></li>
<li class="toctree-l1"><a class="reference internal" href="protocol-state-machines.html">Protocol state machines</a></li>
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Building the documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build">Build</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="protocol-state-machines.html">Protocol state machines</a></li>
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
</ul>
@ -156,23 +155,25 @@
<div class="section" id="building-the-documentation">
<h1>Building the documentation<a class="headerlink" href="#building-the-documentation" title="Permalink to this headline"></a></h1>
<p>The documentation is under the &#8220;docs&#8221; folder, and is written in reStructuredText format. Documentation in HTML format
<p>The documentation is under the <code class="docutils literal"><span class="pre">docs</span></code> folder, and is written in reStructuredText format. Documentation in HTML format
is pre-generated, as well as code documentation, and this can be done automatically via a provided script.</p>
<div class="section" id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline"></a></h2>
<p>To build the documentation, you will need:</p>
<ul class="simple">
<li>GNU Make</li>
<li>Python and pip</li>
<li>Python and pip (tested with Python 2.7.10)</li>
<li>Dokka: <a class="reference external" href="https://github.com/Kotlin/dokka">https://github.com/Kotlin/dokka</a></li>
<li>Sphinx: <a class="reference external" href="http://www.sphinx-doc.org/">http://www.sphinx-doc.org/</a></li>
<li>sphinx_rtd_theme: <a class="reference external" href="https://github.com/snide/sphinx_rtd_theme">https://github.com/snide/sphinx_rtd_theme</a></li>
</ul>
<p>The Dokka JAR file is expected to be placed under the &#8220;lib&#8221; directory, called:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>lib/dokka.jar
<p>The Dokka JAR file needs to be placed under the <code class="docutils literal"><span class="pre">lib</span></code> directory within the <code class="docutils literal"><span class="pre">r3prototyping</span></code> directory, in order for the
script to find it, as in:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>r3prototyping/lib/dokka.jar
</pre></div>
</div>
<p>Note that to install under OS X El Capitan, you will need to tell pip to install under /usr/local, for example:</p>
<p>Note that to install under OS X El Capitan, you will need to tell pip to install under <code class="docutils literal"><span class="pre">/usr/local</span></code>, which can be
done by specifying the installation target on the command line:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>sudo -H pip install --install-option <span class="s1">&#39;--install-data=/usr/local&#39;</span> Sphinx
sudo -H pip install --install-option <span class="s1">&#39;--install-data=/usr/local&#39;</span> sphinx_rtd_theme
</pre></div>
@ -180,15 +181,18 @@ sudo -H pip install --install-option <span class="s1">&#39;--install-data=/usr/l
</div>
<div class="section" id="build">
<h2>Build<a class="headerlink" href="#build" title="Permalink to this headline"></a></h2>
<p>Once the requirements are installed, you can manually build the documentation by changing to the &#8220;docs&#8221; folder, and
running make, for example to produce the documentation in HTML format:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>make html
<p>Once the requirements are installed, you can automatically build the HTML format user documentation and the API
documentation by running the following script:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>scripts/generate-docsite.sh
</pre></div>
</div>
<p>If you type &#8220;make&#8221; by itself, it will list the possible build targets (formats).</p>
<p>Alternatively, the full documentation in HTML format, as well as the API documentation can be built by running the
following script:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>scripts/generate-docsite.sh
<p>Alternatively you can build non-HTML formats from the <code class="docutils literal"><span class="pre">docs</span></code> folder. Change directory to the folder and then run the
following to see a list of all available formats:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>make
</pre></div>
</div>
<p>For example to produce the documentation in HTML format:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>make html
</pre></div>
</div>
</div>
@ -201,10 +205,8 @@ following script:</p>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="protocol-state-machines.html" class="btn btn-neutral float-right" title="Protocol state machines" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tutorial.html" class="btn btn-neutral" title="Writing a contract" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
<a href="codestyle.html" class="btn btn-neutral" title="Code style guide" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>

View File

@ -104,6 +104,7 @@
<ul>
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
</ul>

View File

@ -104,6 +104,7 @@
<ul>
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
</ul>
@ -186,14 +187,12 @@ prove or disprove the following hypothesis:</p>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#messaging-vs-networking">Messaging vs networking</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#interfaces">Interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#in-memory-implementation">In memory implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#network-map-service">Network Map Service</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a>
<ul>
<li class="toctree-l2"><a class="reference internal" href="running-the-demos.html#trader-demo">Trader
demo</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-the-demos.html#irs-demo">IRS demo</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a><ul>
<li class="toctree-l2"><a class="reference internal" href="running-the-demos.html#trader-demo">Trader demo</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-the-demos.html#irs-demo">IRS demo</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a><ul>
@ -256,6 +255,11 @@ prove or disprove the following hypothesis:</p>
<li class="toctree-l2"><a class="reference internal" href="codestyle.html#assertions-and-errors">4. Assertions and errors</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="building-the-docs.html#requirements">Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="building-the-docs.html#build">Build</a></li>
</ul>
</li>
</ul>
</div>
</div>

View File

@ -94,6 +94,7 @@
<li class="toctree-l2"><a class="reference internal" href="#messaging-vs-networking">Messaging vs networking</a></li>
<li class="toctree-l2"><a class="reference internal" href="#interfaces">Interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="#in-memory-implementation">In memory implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#network-map-service">Network Map Service</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
@ -110,6 +111,7 @@
<ul>
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
</ul>
@ -237,6 +239,30 @@ sit around waiting for messages to be delivered. Handlers will then be invoked o
more difficult style of programming that can be used to increase the realism of the unit tests by ensuring multiple
nodes run in parallel, just as they would on a real network spread over multiple machines.</p>
</div>
<div class="section" id="network-map-service">
<h2>Network Map Service<a class="headerlink" href="#network-map-service" title="Permalink to this headline"></a></h2>
<p>Supporting the messaging layer is a network map service, which is responsible for tracking public nodes on the network.
Nodes have an internal component, the network map cache, which contains a copy of the network map. When a node starts up
its cache fetches a copy of the full network map, and requests to be notified of changes. The node then registers itself
with the network map service, and the service notifies subscribers that a new node has joined the network. Nodes do not
automatically deregister themselves, so far (for example) nodes going offline briefly for maintenance</p>
<p>Nodes submit signed changes to the map service, which then forwards them on to nodes which have requested to be notified
of changes. This process achieves basic consensus of the overall network map, although currently it has no formal
process for identifying or recovering from issues such as network outages. Later versions are planned to address this.</p>
<p>Registration change notifications contain a serial number, which indicates their relative ordering, similar to the
serial number on DNS records. These numbers must increase with each change, but are not expected to be sequential.
Changes are then signed by the party whom the node represents to confirm the association between party and node.
The change, signature and public key are then sent to the network map service, which verifies the signature and then
updates the network map accordingly.</p>
<p>The network map cache currently supports:</p>
<ul class="simple">
<li>Looking up nodes by service</li>
<li>Looking up node for a party</li>
<li>Suggesting a node providing a specific service, based on suitability for a contract and parties, for example suggesting</li>
</ul>
<p>an appropriate interest rates oracle for a interest rate swap contract. Currently no recommendation logic is in place
(the code simply picks the first registered node that supports the required service), however.</p>
</div>
</div>
@ -246,8 +272,7 @@ nodes run in parallel, just as they would on a real network spread over multiple
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="running-the-demos.html" class="btn btn-neutral float-right" title="Running the demos" accesskey="n">Next
<span class="fa fa-arrow-circle-right"></span></a>
<a href="running-the-demos.html" class="btn btn-neutral float-right" title="Running the demos" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="data-model.html" class="btn btn-neutral" title="Data model" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>

Binary file not shown.

View File

@ -103,6 +103,7 @@
<ul>
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
</ul>

File diff suppressed because one or more lines are too long