From 564d44f64f5025490a070a7fead8a379232002f9 Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Tue, 28 Feb 2017 18:09:35 -0600
Subject: [PATCH] docs/grpc: expand python docs w/ links to official
 protobuf+gRPC tutorial

---
 docs/grpc/python.md | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/docs/grpc/python.md b/docs/grpc/python.md
index a3faaa917c..58b6d7f6a3 100644
--- a/docs/grpc/python.md
+++ b/docs/grpc/python.md
@@ -1,10 +1,12 @@
 # How to write a Python gRPC client for the Lightning Network Daemon #
 
-This section enumerates what you need to do to write a client that communicates with lnd in Python.
+This section enumerates what you need to do to write a client that communicates
+with lnd in Python.
 
-Lnd uses the gRPC protocol for communication with clients like lncli. gRPC is based on protocol buffers
-and as such, you will need to compile the lnd proto file in Python before you can use it to communicate with
-lnd. The following are the steps to take.
+Lnd uses the gRPC protocol for communication with clients like lncli. gRPC is
+based on protocol buffers and as such, you will need to compile the lnd proto
+file in Python before you can use it to communicate with lnd. The following are
+the steps to take.
 
 * Create a virtual environment for your project
 ```
@@ -14,15 +16,18 @@ $ virtualenv lnd
 ```
 $ source lnd/bin/activate
 ```
-* Install dependencies (googleapis-common-protos is required due to the use of google/api/annotations.proto)
+* Install dependencies (googleapis-common-protos is required due to the use of
+  google/api/annotations.proto)
 ```
 (lnd)$ pip install grpcio grpcio-tools googleapis-common-protos
 ```
-* Clone the google api's repository (required due to the use of google/api/annotations.proto)
+* Clone the google api's repository (required due to the use of
+  google/api/annotations.proto)
 ```
 (lnd)$ git clone https://github.com/googleapis/googleapis.git
 ```
-* Copy the lnd rpc.proto file (you'll find this in lnrpc/rpc.proto) or just download it
+* Copy the lnd rpc.proto file (you'll find this in lnrpc/rpc.proto) or just
+  download it
 ```
 (lnd)$ curl -o rpc.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/rpc.proto
 ```
@@ -31,10 +36,11 @@ $ source lnd/bin/activate
 (lnd)$ python -m grpc_tools.protoc --proto_path=googleapis:. --python_out=. --grpc_python_out=. rpc.proto
 ```
 
-After following these steps, two files `rpc_pb2.py` and `rpc_pb2_grpc.py` will be generated. These files will be
-imported in your project while writing your clients. Here's an example of a simple client that was built using these.
+After following these steps, two files `rpc_pb2.py` and `rpc_pb2_grpc.py` will
+be generated. These files will be imported in your project while writing your
+clients. Here's an example of a simple client that was built using these.
 
-```
+```python
 # python-based lnd client to retrieve and display wallet balance
 
 import grpc
@@ -48,3 +54,12 @@ stub = lnrpc.LightningStub(channel)
 response = stub.WalletBalance(ln.WalletBalanceRequest(witness_only=True))
 print(response.balance)
 ```
+
+With the above, you should have all the `lnd` related `gRPC` dependencies
+installed locally into your virtual environment. In order to get up to speed
+with `protofbuf` usage from Python, see [this official `protobuf` tutorial for
+Python](https://developers.google.com/protocol-buffers/docs/pythontutorial).
+Additionally, [this official gRPC
+resource](http://www.grpc.io/docs/tutorials/basic/python.html) details how to
+drive `gRPC` from Python including the basics of making RPC calls, streaming
+RPC's (bi-directional and uni-directional), etc.