restructured docs

adding a note about status streaming Signed-off-by: Sara <lira.lemur@gmail.com>
hyperledger · Sep 9, 2019 · 3d2a4e9 · 3d2a4e9
1 parent d891978
commit 3d2a4e9
Show file tree

Hide file tree

Showing 38 changed files with 343 additions and 465 deletions.
diff --git a/docs/permissions_compiler/compiler.py b/docs/permissions_compiler/compiler.py
@@ -114,7 +114,7 @@
     commons_path = [os.path.pardir] * 2 + ['example', 'python', 'permissions', 'commons.py']
     result.extend(rst.listing(commons_path, 'commons.py'))
 
-with open('maintenance/permissions.rst', 'w') as output:
+with open('develop/api/permissions.rst', 'w') as output:
     content = "\n".join(result)
     output.write(content)
     output.flush()

diff --git a/docs/permissions_compiler/glossary.py b/docs/permissions_compiler/glossary.py
@@ -5,7 +5,7 @@
 
 def read_titles(level_char='='):
     headings = []
-    with open('core_concepts/glossary.rst') as gfile:
+    with open('before_start/glossary.rst') as gfile:
         lines = gfile.readlines()
         prevline = ''
         prevlen = 0
@@ -22,6 +22,6 @@ def titles_to_links(titles):
     d = {}
     for title in titles:
         title = title.strip().lower()
-        anchor = '../core_concepts/glossary.html#' + title.replace(' ', '-')
+        anchor = '../../before_start/glossary.html#' + title.replace(' ', '-')
         d[title] = anchor
     return d
diff --git a/docs/permissions_compiler/rst.py b/docs/permissions_compiler/rst.py
@@ -93,7 +93,7 @@ def listing(compile_time_path, caption='', lines_range=None, lang='python'):
         print('File not found: {} (compile time path)'.format(path))
         return []
 
-    docs_time_path = [os.path.pardir] + list(compile_time_path)
+    docs_time_path = [os.path.pardir] * 2 + list(compile_time_path)
     path = os.path.join(*docs_time_path)
     result = [
         '.. literalinclude:: {}'.format(path),
@@ -143,7 +143,7 @@ def excerpt(permission):
     :param permission: name of permission to list, used as a part of filename
     :return: rst lines
     """
-    compile_time_path = [os.path.pardir, os.path.pardir, 'example', 'python', 'permissions', '{}.py'.format(permission)]
+    compile_time_path = [os.path.pardir] * 2 + ['example', 'python', 'permissions', '{}.py'.format(permission)]
     path = os.path.join(*compile_time_path)
     result = []
     if not os.path.isfile(path):

diff --git a/docs/source/architecture/index.rst → docs/source/before_start/architecture.rst b/docs/source/architecture/index.rst → docs/source/before_start/architecture.rst
@@ -1,8 +1,7 @@
 .. _architecture:
 
-************
-Architecture
-************
+What's inside Iroha?
+====================
 
 HL Iroha network consists of several essential components that provide the communication between the nodes. You can learn about them below.
 
@@ -78,15 +77,15 @@ Block Consensus (YAC)
 
 *Consensus, as a component*
 
-    Consensus is the heart of the blockchain - it preserves a consistent state among the `peers <../core_concepts/glossary.html#peer>`__ within a peer network.
-    Iroha uses own consensus algorithm called Yet Another Consensus (aka YAC).
+Consensus is the heart of the blockchain - it preserves a consistent state among the `peers <../core_concepts/glossary.html#peer>`__ within a peer network.
+Iroha uses own consensus algorithm called Yet Another Consensus (aka YAC).
 
-    You can check out a video where HL Iroha maintainer thoroughly explains the principles of consensus and YAC in particular `here <https://youtu.be/mzuAbalxOKo>`__.
+You can check out a video with a thorough explanation of the principles of consensus and YAC in particular `here <https://youtu.be/mzuAbalxOKo>`__.
 
-    Distinctive features of YAC algorithm are its scalability, performance and `Byzantine fault tolerance <https://en.wikipedia.org/wiki/Byzantine_fault_tolerance>`_.
+Distinctive features of YAC algorithm are its scalability, performance and `Byzantine fault tolerance <https://en.wikipedia.org/wiki/Byzantine_fault_tolerance>`_.
 
-    To ensure consistency in the network, if there are missing blocks, they will be downloaded from another peer via `Synchronizer <#synchronizer>`__.
-    Committed blocks are stored in `Ametsuchi <#ametsuchi>`__ block storage.
+To ensure consistency in the network, if there are missing blocks, they will be downloaded from another peer via `Synchronizer <#synchronizer>`__.
+Committed blocks are stored in `Ametsuchi <#ametsuchi>`__ block storage.
 
 For general definition of the consensus, please check `this link <../core_concepts/glossary.html#consensus>`_.
 

diff --git a/docs/source/core_concepts/index.rst → docs/source/before_start/core_concepts.rst b/docs/source/core_concepts/index.rst → docs/source/before_start/core_concepts.rst
@@ -7,9 +7,6 @@ Why Iroha runs in a network? How to understand the objects inside and outside th
 How peers in the network collaborate and decide which data to put into the blockchain?
 We will look through the basics of Iroha in this section.
 
-Sections
---------
-
 .. toctree::
     :maxdepth: 1
 

diff --git a/docs/source/core_concepts/er_model.rst → docs/source/before_start/er_model.rst b/docs/source/core_concepts/er_model.rst → docs/source/before_start/er_model.rst
diff --git a/docs/source/core_concepts/glossary.rst → docs/source/before_start/glossary.rst b/docs/source/core_concepts/glossary.rst → docs/source/before_start/glossary.rst
@@ -65,7 +65,7 @@ Solving that issue -- known as the consensus problem -- is important in distribu
 
 *Consensus, as an algorithm*
 
-    An algorithm to achieve agreement on a block among peers in the network. By having it in the system, reliability is increased.
+An algorithm to achieve agreement on a block among peers in the network. By having it in the system, reliability is increased.
 
 For consensus as Iroha's component, please check `this link <../architecture/index.html#block-consensus-yac>`_.
 
@@ -163,12 +163,16 @@ Transaction Statuses
 --------------------
 
 Hyperledger Iroha supports both push and pull interaction mode with a client.
-A client that uses pull mode requests status updates about transactions from Iroha peer by sending transaction hashes and awaiting a response. 
+A client that uses pull mode requests status updates about transactions from Iroha peer by sending transaction hashes and awaiting a response.
 On the contrary, push interaction is performed by listening of an event stream for each transaction.
 In any of these modes, the set of transaction statuses is the same:
 
  .. image:: ./../../image_assets/tx_status.png
 
+.. note::
+    We've written a great Medium `article about Status streaming feature in Iroha <https://medium.com/iroha-contributors/status-streaming-in-hl-iroha-5503487ffcfd>`_.
+    Check it out and let us know what you think in the comments!
+
 Transaction Status Set
 ^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/source/before_start/index.rst b/docs/source/before_start/index.rst
@@ -0,0 +1,15 @@
+.. _before_start:
+
+===============
+Before we start
+===============
+
+Iroha is a system that can work with different concepts, and for your convenience we would like you to look through them so you could familiarise yourself with what you will be dealing with. That can be done in "Core concepts section".
+
+To learn, what Iroha is made of, please check out "What's inside Iroha?"
+
+.. toctree::
+      :maxdepth: 1
+
+      core_concepts.rst
+      architecture.rst
diff --git a/docs/source/guides/build.rst → docs/source/build/index.rst b/docs/source/guides/build.rst → docs/source/build/index.rst
@@ -1,5 +1,6 @@
 .. _build-guide:
 
+==============
 Building Iroha
 ==============
 
@@ -19,7 +20,7 @@ There will be 3 steps:
   this process explained in details in the :ref:`getting-started` page of this documentation.
 
 Prerequisites
--------------
+=============
 
 In order to successfully build Iroha, we need to configure the environment.
 There are several ways to do it and we will describe all of them.
@@ -81,19 +82,13 @@ When it is done, you need to run the development environment. Run the
 
 After you execute this script, the following things will happen:
 
-#. The script will check whether you have containers with Iroha already running.
-Successful completion finishes with the new container shell.
+#. The script will check whether you have containers with Iroha already running. Successful completion finishes with the new container shell.
 
-#. The script will download ``hyperledger/iroha:develop-build`` and ``postgres`` images.
-``hyperledger/iroha:develop-build`` image contains all development dependencies and is
-based on top of ``ubuntu:16.04``. ``postgres`` image is required for starting
-and running Iroha.
+#. The script will download ``hyperledger/iroha:develop-build`` and ``postgres`` images. ``hyperledger/iroha:develop-build`` image contains all development dependencies and is based on top of ``ubuntu:16.04``. ``postgres`` image is required for starting and running Iroha.
 
 #. Two containers are created and launched.
 
-#. The user is attached to the interactive environment for development and
-testing with ``iroha`` folder mounted from the host machine. Iroha folder
-is mounted to ``/opt/iroha`` in Docker container.
+#. The user is attached to the interactive environment for development and testing with ``iroha`` folder mounted from the host machine. Iroha folder is mounted to ``/opt/iroha`` in Docker container.
 
 Now your are ready to build Iroha! Please go directly to `Building Iroha <#build-process>`_ section.
 
@@ -174,7 +169,7 @@ PostgreSQL is not a build dependency, but it is recommended to install it now fo
 Now you are ready to `install Iroha dependencies <#installing-dependencies-with-vcpkg-dependency-manager>`_.
 
 Installing dependencies with Vcpkg Dependency Manager
---------------------------------------------------------
+=====================================================
 
 Currently we use Vcpkg as a dependency manager for all platforms - Linux, Windows and MacOS.
 We use a fixed version of Vcpkg to ensure the patches we need will work.
@@ -216,7 +211,7 @@ Save it somewhere for later use and move to `Building Iroha <#build-process>`_ s
   prefixed with ``x86`` term instead of ``x64``.
 
 Build Process
--------------
+=============
 
 Cloning the Repository
 ^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst
@@ -0,0 +1,5 @@
+==================
+Join the Community
+==================
+
+.. include:: ../../../CONTRIBUTING.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -67,6 +67,9 @@
         'searchbox.html',
     ]
 }
+html_theme_options = {
+    'navigation_depth': 3, #default is 4 - changed for better looks
+}
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -94,7 +97,7 @@
     # 'figure_align': 'htbp',
 }
 
-# Read variables for 
+# Read variables for
 # common settings and locale:
 with open('common.yaml', 'r') as stream:
     common = yaml.load(stream)
@@ -103,7 +106,7 @@
     description = common.get('description')
     copyright = common.get('copyright')
     author = common.get('author')
-with open('locale.yaml', 'r') as stream:    
+with open('locale.yaml', 'r') as stream:
     locale = yaml.load(stream)
     language = locale.get('language')
     if locale.get('locale_dirs'):

diff --git a/docs/source/guides/configuration.rst → docs/source/configure/index.rst b/docs/source/guides/configuration.rst → docs/source/configure/index.rst
@@ -1,7 +1,13 @@
 .. _configuration:
 
-Configuration
-=============
+=========
+Configure
+=========
+
+.. toctree::
+      :maxdepth: 1
+
+      torii-tls.rst
 
 In this section we will understand how to configure Iroha. Let's take a look
 at ``example/config.sample``
@@ -39,7 +45,7 @@ As you can see, configuration file is a valid ``json`` structure. Let's go
 line-by-line and understand what every parameter means.
 
 Deployment-specific parameters
-------------------------------
+==============================
 
 - ``block_store_path`` sets path to the folder where blocks are stored.
 - ``torii_port`` sets the port for external communications. Queries and
@@ -83,7 +89,7 @@ The ``database`` section fields:
   For example, when iroha needs to create or drop its working database, it must use another database to connect to PostgreSQL.
 
 Environment-specific parameters
--------------------------------
+===============================
 
 - ``max_proposal_size`` is the maximum amount of transactions that can be in
   one proposal, and as a result in a single block as well. So, by changing this
@@ -134,7 +140,7 @@ Environment-specific parameters
   "bddd58404d1315e0eb27902c5d7c8eb0602c16238f005773df406bc191308929"}]``
 
 Logging
--------
+=======
 
 In Iroha logging can be adjusted as granularly as you want.
 Each component has its own logging configuration with properties inherited from

diff --git a/docs/source/guides/torii-tls.rst → docs/source/configure/torii-tls.rst b/docs/source/guides/torii-tls.rst → docs/source/configure/torii-tls.rst
diff --git a/docs/source/contribution/index.rst b/docs/source/contribution/index.rst
diff --git a/docs/source/deploy/index.rst b/docs/source/deploy/index.rst
@@ -0,0 +1,17 @@
+.. _deploy-guide:
+
+======
+Deploy
+======
+
+Hyperledger Iroha can be deployed in different ways, depending on the perspective and the purpose.
+There can be either a single node deployed, or multiple nodes running in several containers on a local machine or spread across the network — so pick any case you need.
+This page describes different scenarios and is intended to act as a how-to guide for users, primarily trying out Iroha for the first time.
+
+.. toctree::
+      :maxdepth: 1
+
+      single.rst
+      multiple.rst
+      k8s-deployment.rst
+      troubles.rst
diff --git a/docs/source/guides/k8s-deployment.rst → docs/source/deploy/k8s-deployment.rst b/docs/source/guides/k8s-deployment.rst → docs/source/deploy/k8s-deployment.rst
@@ -1,3 +1,4 @@
+=====================================
 Deploying Iroha on Kubernetes cluster
 =====================================
 .. TODO: Update the guide. https://soramitsu.atlassian.net/browse/DOPS-391

diff --git a/docs/source/deploy/multiple.rst b/docs/source/deploy/multiple.rst
@@ -0,0 +1,19 @@
+=========================================
+Running multiple instances (peer network)
+=========================================
+
+In order to set up a peer network, one should follow routines, described in this section.
+In this version, we support manual deployment and automated by Ansible Playbook.
+Choose an option, that meets your security criteria and other needs.
+
+Manually
+--------
+
+By manual deployment, we mean that Iroha peer network is set up without automated assistance.
+It is similar to the process of running a single local instance, although the difference is the genesis block includes more than a single peer.
+In order to form a block, which includes more than a single peer, or requires customization for your needs, please take a look at `:ref:`deploy_troubles` section.
+
+Automated
+---------
+
+Follow `this guide <https://github.com/hyperledger/iroha-deploy/blob/master/ansible/roles/iroha-docker/README.md>`__