docs: edits for rst & other cleanup

docs/basecoin-basics.rst

@@ -74,24 +74,28 @@ Install
 
 With go, it's one command:
 
-.. code:: shelldown[0]
+..  code:: shelldown[0]
+
+::
 
     go get -u github.com/tendermint/basecoin/cmd/...
 
-If you have trouble, see the `installation guide <install.md>`__.
+If you have trouble, see the `installation guide <./install.html>`__.
 
 Note the above command installs two binaries: ``basecoin`` and
 ``basecli``. The former is the running node. The latter is a
 command-line light-client. This tutorial assumes you have a 'fresh'
-working environment. See `how to clean up, below <#clean-up>`__.
+working environment. See how to clean up below.
 
 Generate some keys
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Let's generate two keys, one to receive an initial allocation of coins,
 and one to send some coins to later:
 
-.. code:: shelldown[1]
+..  code:: shelldown[1]
+
+::
 
     basecli keys new cool
     basecli keys new friend
@@ -105,14 +109,18 @@ Initialize Basecoin
 
 To initialize a new Basecoin blockchain, run:
 
-.. code:: shelldown[2]
+..  code:: shelldown[2]
+
+::
 
     basecoin init <ADDRESS>
 
 If you prefer not to copy-paste, you can provide the address
 programatically:
 
-.. code:: shelldown[3]
+..  code:: shelldown[3]
+
+::
 
     basecoin init $(basecli keys get cool | awk '{print $2}')
 
@@ -124,12 +132,14 @@ Basecoin tool </docs/guide/basecoin-tool.md>`__.
 If you like, you can manually add some more accounts to the blockchain
 by generating keys and editing the ``~/.basecoin/genesis.json``.
 
-Start
+Start Basecoin
------
+~~~~~~~~~~~~~~
 
 Now we can start Basecoin:
 
-.. code:: shelldown[4]
+..  code:: shelldown[4]
+
+::
 
     basecoin start
 
@@ -143,7 +153,9 @@ light-client utility. Basecli is used for sending transactions and
 querying the state. Leave Basecoin running and open a new terminal
 window. Here run:
 
-.. code:: shelldown[5]
+..  code:: shelldown[5]
+
+::
 
     basecli init --node=tcp://localhost:46657 --genesis=$HOME/.basecoin/genesis.json
 
@@ -153,17 +165,19 @@ some trusted source, so all queries done with ``basecli`` can be
 cryptographically proven to be correct according to a known validator
 set.
 
-Note: that --genesis only works if there have been no validator set
+Note: that ``--genesis`` only works if there have been no validator set
 changes since genesis. If there are validator set changes, you need to
 find the current set through some other method.
 
 Send transactions
------------------
+~~~~~~~~~~~~~~~~~
 
 Now we are ready to send some transactions. First Let's check the
 balance of the two accounts we setup earlier:
 
-.. code:: shelldown[6]
+..  code:: shelldown[6]
+
+::
 
     ME=$(basecli keys get cool | awk '{print $2}')
     YOU=$(basecli keys get friend | awk '{print $2}')
@@ -173,20 +187,26 @@ balance of the two accounts we setup earlier:
 The first account is flush with cash, while the second account doesn't
 exist. Let's send funds from the first account to the second:
 
-.. code:: shelldown[7]
+..  code:: shelldown[7]
+
+::
 
     basecli tx send --name=cool --amount=1000mycoin --to=$YOU --sequence=1
 
 Now if we check the second account, it should have ``1000`` 'mycoin'
 coins!
 
-.. code:: shelldown[8]
+..  code:: shelldown[8]
+
+::
 
     basecli query account $YOU
 
 We can send some of these coins back like so:
 
-.. code:: shelldown[9]
+..  code:: shelldown[9]
+
+::
 
     basecli tx send --name=friend --amount=500mycoin --to=$ME --sequence=1
 
@@ -195,20 +215,26 @@ send from.
 
 If we try to send too much, we'll get an error:
 
-.. code:: shelldown[10]
+..  code:: shelldown[10]
+
+::
 
     basecli tx send --name=friend --amount=500000mycoin --to=$ME --sequence=2
 
 Let's send another transaction:
 
-.. code:: shelldown[11]
+..  code:: shelldown[11]
 
-    basecli tx send --name=cool --amount=2345mycoin --to=$YOU --sequence=2
+::
+
+   basecli tx send --name=cool --amount=2345mycoin --to=$YOU --sequence=2
 
 Note the ``hash`` value in the response - this is the hash of the
 transaction. We can query for the transaction by this hash:
 
-.. code:: shelldown[12]
+..  code:: shelldown[12]
+
+::
 
     basecli query tx <HASH>
 
@@ -228,9 +254,6 @@ and it is secure to do so. So, if you wonder why the query may take a
 second... there is a lot of work going on in the background to make sure
 even a lying full node can't trick your client.
 
-In a latter `guide on InterBlockchain Communication <ibc.md>`__, we'll
-use these proofs to post transactions to other chains.
-
 Accounts and Transactions
 -------------------------
 
@@ -248,7 +271,9 @@ unlike Bitcoin's use of Unspent Transaction Outputs (UTXOs). Note
 Basecoin is a multi-asset cryptocurrency, so each account can have many
 different kinds of tokens.
 
-.. code:: golang
+..  code:: golang
+
+::
 
     type Account struct {
         PubKey   crypto.PubKey `json:"pub_key"` // May be nil, if not known.
@@ -285,7 +310,9 @@ a list of outputs, and transfers all the tokens listed in the inputs
 from their corresponding accounts to the accounts listed in the output.
 The ``SendTx`` is structured as follows:
 
-.. code:: golang
+..  code:: golang
+
+::
 
     type SendTx struct {
       Gas     int64      `json:"gas"`
@@ -347,19 +374,15 @@ To remove all the files created and refresh your environment (e.g., if
 starting this tutorial again or trying something new), the following
 commands are run:
 
-.. code:: shelldown[end-of-tutorials]
+..  code:: shelldown[end-of-tutorials]
+
+::
 
     basecli reset_all
     rm -rf ~/.basecoin
 
-Conclusion
-----------
-
 In this guide, we introduced the ``basecoin`` and ``basecli`` tools,
 demonstrated how to start a new basecoin blockchain and how to send
 tokens between accounts, and discussed the underlying data types for
 accounts and transactions, specifically the ``Account`` and the
-``SendTx``. In the `next guide <basecoin-plugins.md>`__, we introduce
+``SendTx``.
-the Basecoin plugin system, which uses a new transaction type, the
-``AppTx``, to extend the functionality of the Basecoin system with
-arbitrary logic.

docs/basecoin-tool.rst

@@ -54,31 +54,33 @@
    . $DIR/shunit2
    -->
 
-The Basecoin Tool
+Basecoin The Tool
 =================
 
-In previous tutorials we learned the `basics of the Basecoin
+We previously learned about basecoin basics. In this tutorial, we
-CLI </docs/guide/basecoin-basics.md>`__ and `how to implement a
-plugin </docs/guide/basecoin-plugins.md>`__. In this tutorial, we
 provide more details on using the Basecoin tool.
 
 Generate a Key
-==============
+--------------
 
 Generate a key using the ``basecli`` tool:
 
-.. code:: shelldown[0]
+.. comment code:: shelldown[0]
+
+::
 
     basecli keys new mykey
     ME=$(basecli keys get mykey | awk '{print $2}')
 
 Data Directory
-==============
+--------------
 
 By default, ``basecoin`` works out of ``~/.basecoin``. To change this,
 set the ``BCHOME`` environment variable:
 
-.. code:: shelldown[1]
+.. comment code:: shelldown[1]
+
+::
 
     export BCHOME=~/.my_basecoin_data
     basecoin init $ME
@@ -86,19 +88,23 @@ set the ``BCHOME`` environment variable:
 
 or
 
-.. code:: shelldown[2]
+.. comment code:: shelldown[2]
+
+::
 
     BCHOME=~/.my_basecoin_data basecoin init $ME
     BCHOME=~/.my_basecoin_data basecoin start
 
 ABCI Server
-===========
+-----------
 
 So far we have run Basecoin and Tendermint in a single process. However,
 since we use ABCI, we can actually run them in different processes.
 First, initialize them:
 
-.. code:: shelldown[3]
+.. comment code:: shelldown[3]
+
+::
 
     basecoin init $ME
 
@@ -107,13 +113,17 @@ the information for both Basecoin and Tendermint.
 
 Now, In one window, run
 
-.. code:: shelldown[4]
+.. comment code:: shelldown[4]
+
+::
 
     basecoin start --without-tendermint
 
 and in another,
 
-.. code:: shelldown[5]
+.. comment code:: shelldown[5]
+
+::
 
     TMROOT=~/.basecoin tendermint node
 
@@ -122,36 +132,40 @@ You should see Tendermint start making blocks!
 Alternatively, you could ignore the Tendermint details in
 ``~/.basecoin/genesis.json`` and use a separate directory by running:
 
-.. code:: shelldown[6]
+.. comment code:: shelldown[6]
+
+::
 
     tendermint init
     tendermint node
 
-For more details on using ``tendermint``, see `the
+See the `tendermint documentation <https://tendermint.readthedocs.io>`__ for more information.
-guide <https://tendermint.com/docs/guides/using-tendermint>`__.
 
 Keys and Genesis
-================
+----------------
 
 In previous tutorials we used ``basecoin init`` to initialize
 ``~/.basecoin`` with the default configuration. This command creates
 files both for Tendermint and for Basecoin, and a single
-``genesis.json`` file for both of them. For more information on these
+``genesis.json`` file for both of them. You can read more about these
-files, see the `guide to using
+files in the Tendermint documentation.
-Tendermint <https://tendermint.com/docs/guides/using-tendermint>`__.
 
 Now let's make our own custom Basecoin data.
 
 First, create a new directory:
 
-.. code:: shelldown[7]
+.. comment code:: shelldown[7]
+
+::
 
     mkdir example-data
 
 We can tell ``basecoin`` to use this directory by exporting the
 ``BCHOME`` environment variable:
 
-.. code:: shelldown[8]
+.. comment code:: shelldown[8]
+
+::
 
     export BCHOME=$(pwd)/example-data
 
@@ -160,13 +174,17 @@ this variable to your shell startup scripts (eg. ``~/.bashrc``).
 
 Now, let's create a new key:
 
-.. code:: shelldown[9]
+.. comment code:: shelldown[9]
+
+::
 
     basecli keys new foobar
 
 The key's info can be retrieved with
 
-.. code:: shelldown[10]
+.. comment code:: shelldown[10]
+
+::
 
     basecli keys get foobar -o=json
 
@@ -228,27 +246,31 @@ need this flag because we were using the default chain ID
 ("test\_chain\_id"). Now that we're using a custom chain, we need to
 specify the chain explicitly on the command line.
 
-Note we have also left out the details of the Tendermint genesis. These
+Note we have also left out the details of the Tendermint genesis. See the
-are documented in the `Tendermint
+`Tendermint documentation <https://tendermint.readthedocs.io>`__ for more
-guide <https://tendermint.com/docs/guides/using-tendermint>`__.
+information.
 
 Reset
-=====
+-----
 
 You can reset all blockchain data by running:
 
-.. code:: shelldown[11]
+.. (comment) code:: shelldown[11]
+
+::
 
     basecoin unsafe_reset_all
 
 Similarly, you can reset client data by running:
 
-.. code:: shelldown[12]
+.. (comment) code:: shelldown[12]
+
+::
 
     basecli reset_all
 
 Genesis
-=======
+-------
 
 Any required plugin initialization should be constructed using
 ``SetOption`` on genesis. When starting a new chain for the first time,

docs/overview.rst

@@ -1,24 +1,17 @@
-Quark Overview
+SDK Overview
 ==============
 
-The quark middleware design optimizes flexibility and security. The
+The SDK middleware design optimizes flexibility and security. The
 framework is designed around a modular execution stack which allows
 applications to mix and match modular elements as desired. Along side,
 all modules are permissioned and sandboxed to isolate modules for
 greater application security.
 
-For more explanation please see the `standard library <stdlib.md>`__ and
-`glossary <glossary.md>`__ documentation.
-
-For a more interconnected schematics see these
-`framework <graphics/overview-framework.png>`__ and
-`security <graphics/overview-security.png>`__ overviews.
-
 Framework Overview
 ------------------
 
-Transactions (tx)
+Transactions
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 
 Each transaction passes through the middleware stack which can be
 defined uniquely by each application. From the multiple layers of
@@ -32,13 +25,13 @@ Execution Stack
 
 Middleware components allow for code reusability and integrability. A
 standard set of middleware are provided and can be mix-and-matched with
-custom middleware. Some of the `standard library <stdlib.md>`__
+custom middleware. Some of the `standard library <./stdlib.html>`__
 middlewares provided in this package include: - Logging - Recovery -
 Signatures - Chain - Nonce - Fees - Roles -
 Inter-Blockchain-Communication (IBC)
 
 As a part of stack execution the state space provided to each middleware
-is isolated (see `Data Store <overview.md#data-store>`__). When
+is isolated ``Data Store`` below. When
 executing the stack, state-recovery checkpoints can be assigned for
 stack execution of ``CheckTx`` or ``DeliverTx``. This means, that all
 state changes will be reverted to the checkpoint state on failure when
@@ -59,7 +52,7 @@ types must first be registered with the dispatcher. Once registered the
 middleware stack or any other handler can call the dispatcher to execute
 a transaction. Similarly to the execution stack, when executing a
 transaction the dispatcher isolates the state space available to the
-designated module (see `Data Store <overview.md#data-store>`__).
+designated module (see ``Data Store`` below).
 
 Security Overview
 -----------------
@@ -93,5 +86,3 @@ accessible to it under the assigned key ``bar``. This effectively makes
 app prefixing invisible to each module while preventing each module from
 affecting each other module. Under this model no two registered modules
 are permitted to have the same namespace.
-
-