updated docs

docs/index.rst

@@ -2,8 +2,22 @@ Coinbits Documentation
 ======================
 
 .. note ::
-    This library assumes you have a working familiarity with the Bitcoin Protocol.
+    This library assumes you have a working familiarity with the `Bitcoin Protocol <https://en.bitcoin.it/wiki/Protocol_specification>`_.
 
+Coinbits provides the basic serialization / deserialization code necessary to operate as a peer on the Bitcoin network.  Many utilities are provided to help with buffering input, creating transactions, and key management.
+
+This library could be used to do any of the following things easily:
+
+ * To create a full Peer node that accepts and validates transactions, stores blocks, and responds to inventory requests
+ * To query blocks from nodes on the network
+ * To map the bitcoin network, asking each peer for a list of peers, then those peers for peers, etc.
+
+Basically, anything that requires interaction on the P2P network could utilize this library.
+
+.. include:: quick_example.rst
+
+Getting Started
+===============
 .. toctree::
    :maxdepth: 3
    :titlesonly:

docs/intro.rst

@@ -6,14 +6,13 @@ The easiest (and best) way to install coinbits is through `pip <http://www.pip-i
   $ pip install coinbits
       
 
-Usage
-=====
-Assuming you want to run a basic client:
+.. include:: quick_example.rst
 
-.. literalinclude:: ../examples/client.py
-
-Check out the examples folder for other examples.
+Sending a Transaction
+=====================
+Creating a transaction and sending it on the network is pretty straightforward.  All you need to know is the private key that will be "sending" the money, the receipient's address, and the output transaction to use as the input for this transaction.  Here's an example that sends 2M Satoshis after connecting to the P2P network:
 
+.. literalinclude:: ../examples/sendmoney.py
 
 Running Tests
 =============

docs/quick_example.rst

@@ -0,0 +1,7 @@
+Quick Example
+=============
+Coinbits includes a basic client example for interacting on the peer-to-peer network.  Here's an example of a client that extends :py:mod:`~coinbits.client.BitcoinClient` and requests information on a block hash:
+
+.. literalinclude:: ../examples/client.py
+
+The :py:mod:`~coinbits.client.BitcoinClient.connected` method will be called as soon as the client has connected and finished handshaking.  The :py:mod:`~coinbits.protocol.serializers` module contains all of the messages that can be serialized on the network, like the :py:mod:`~coinbits.protocol.serializers.GetBlocks` message command (described `here <https://en.bitcoin.it/wiki/Protocol_specification#getblocks>`_).  In this case, the send_message and message_received methods have been overwritten just for debugging.  The handle_inv method is an example of the method dispatch - any message command type can have an associated handle_* method that will be called whenever a message of that type is received.

examples/sendmoney.py

@@ -10,15 +10,16 @@ def connected(self):
         key = PrivateKey('e1385343f7ea362b0de7e5772a6c766d44ce4bf69e1380381630bf1892c638d5')
         teller = Teller(key)
 
-        # now, specify the Transaction hash and output index to use for this transaction
+        # specify the origin transaction hash and output index to use for this transaction's input
+        hexouthash = '8ed9e37a3c585ad2b28ebc9a7a76ff0bf250bd4a1d19cb42f8d29d62da8d3e67'
         outpoint = OutPoint()
-        outpoint.out_hash = int("8ed9e37a3c585ad2b28ebc9a7a76ff0bf250bd4a1d19cb42f8d29d62da8d3e67", 16)
+        outpoint.out_hash = int(hexouthash, 16)
         outpoint.index = 0
 
         # pay 2M Satoshis to 1wYiNC2EERnKPWP7QbvWGEfNprtHg1bsz
         tx = teller.make_standard_tx(outpoint, '1wYiNC2EERnKPWP7QbvWGEfNprtHg1bsz', 2000000)
 
-        print "Hash to watch for:", tx.calculate_hash()
+        print "New transaction's hash:", tx.calculate_hash()
         self.send_message(tx)
 
     def handle_inv(self, message_header, message):