mirror of
https://github.com/corda/corda.git
synced 2025-06-16 14:18:20 +00:00
Rebuild user documentation
This commit is contained in:
Ross Nicoll
54
docs/build/html/_sources/building-the-docs.txt
vendored
Normal file
54
docs/build/html/_sources/building-the-docs.txt
vendored
Normal 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
|
||||
1
docs/build/html/_sources/index.txt
vendored
1
docs/build/html/_sources/index.txt
vendored
@ -47,4 +47,5 @@ Read on to learn:
|
||||
|
||||
visualiser
|
||||
codestyle
|
||||
building-the-docs
|
||||
|
||||
|
||||
25
docs/build/html/_sources/messaging.txt
vendored
25
docs/build/html/_sources/messaging.txt
vendored
@ -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.
|
||||
|
||||
52
docs/build/html/building-the-docs.html
vendored
52
docs/build/html/building-the-docs.html
vendored
@ -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 “docs” 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 “lib” 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">'--install-data=/usr/local'</span> Sphinx
|
||||
sudo -H pip install --install-option <span class="s1">'--install-data=/usr/local'</span> sphinx_rtd_theme
|
||||
</pre></div>
|
||||
@ -180,15 +181,18 @@ sudo -H pip install --install-option <span class="s1">'--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 “docs” 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 “make” 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>
|
||||
|
||||
|
||||
1
docs/build/html/genindex.html
vendored
1
docs/build/html/genindex.html
vendored
@ -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>
|
||||
|
||||
|
||||
|
||||
16
docs/build/html/index.html
vendored
16
docs/build/html/index.html
vendored
@ -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>
|
||||
|
||||
29
docs/build/html/messaging.html
vendored
29
docs/build/html/messaging.html
vendored
@ -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>
|
||||
|
||||
BIN
docs/build/html/objects.inv
vendored
BIN
docs/build/html/objects.inv
vendored
Binary file not shown.
1
docs/build/html/search.html
vendored
1
docs/build/html/search.html
vendored
@ -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>
|
||||
|
||||
|
||||
|
||||
2
docs/build/html/searchindex.js
vendored
2
docs/build/html/searchindex.js
vendored
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user