updated documentation

docs/source/index.rst

@@ -7,7 +7,7 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    installation
    usage

docs/source/modify.rst

@@ -4,42 +4,43 @@
 modify
 ======
 
-Demonstrates how to modify requests. This is particularly useful for sending curved balls to your applications, and make sure they deal with them correctly. import hoverpy's main class: HoverPy 
+Let's look into mutating responses using middleware. This is particularly useful for sending curved balls to your applications, and make sure they deal with them correctly. 
 
 ::
 
 >>> from hoverpy import HoverPy
-
-
-Import requests for http 
-
-::
-
 >>> import requests
+>>> with HoverPy(
+>>>         modify=True,
+>>>         middleware="python examples/modify/modify_payload.py") as hoverpy:
 
 
-Create our HoverPy object with modify and middleware enabled. please note this brings in ```python examples/modify/modify_payload.py``` which will get run on every request 
+Above we created our HoverPy object with modify and middleware enabled. Please note this brings in ```python examples/modify/modify_payload.py``` which will get run on every request. 
 
 ::
 
->>> with HoverPy(
->>>     flags=[
->>>         "-modify",
->>>         "-middleware",
->>>         "python examples/modify/modify_payload.py"]) as hoverpy:
+>>>     for i in range(30):
+>>>         r = requests.get("http://time.jsontest.com")
 
 
-Our middleware is designed to random return an empty body instead of what it's supposed to return (the curren time). This is a good example of how to alter your dependencies, and adequately test and react based on their content 
+Let's make 30 requests to time.jsontest.com which simply gets us the current local time 
 
 ::
 
->>>     for i in range(30):
->>>         r = requests.get("http://time.jsontest.com")
 >>>         if "time" in r.json().keys():
 >>>             print(
 >>>                 "response successfully modified, current date is " +
 >>>                 r.json()["time"])
+
+
+Time ``time`` key is inside the response, which is what we expected. 
+
+::
+
 >>>         else:
 >>>             print("something went wrong - deal with it gracefully")
 
 
+However if the ``time`` key isn't in the response, then something clearly went wrong. Next let's take a look at the middleware.
+
+.. include:: modify_payload.rst 

docs/source/modify_payload.rst

@@ -0,0 +1,78 @@
+.. modify_payload
+
+==============
+modify_payload
+==============
+
+
+
+::
+
+>>> #!/usr/bin/env python
+
+
+This is the payload modification script. It truly allows us to do all types of weird, wild and wonderful mutations to the data that gets sent back to our application. Let's begin by imporing what we'll need. 
+
+::
+
+>>> import sys
+>>> import json
+>>> import logging
+>>> import random
+>>> logging.basicConfig(filename='middleware.log', level=logging.DEBUG)
+>>> logging.debug('Middleware "modify_request" called')
+
+
+Above we've also configured our logging. This is essential, as it's difficult to figure out what went wrong otherwise. 
+
+::
+
+>>> def main():
+>>>     data = sys.stdin.readlines()
+>>>     payload = data[0]
+>>>     logging.debug(payload)
+>>>     payload_dict = json.loads(payload)
+
+
+The response to our request gets sent to middleware via stdin. Therefore, we are really only interested in the first line. 
+
+::
+
+>>>     payload_dict['response']['status'] = random.choice([200, 201])
+
+
+Let's randomly switch the status for the responses between 200, and 201. This helps us build a resilient client, that can deal with curved balls. 
+
+::
+
+>>>     if random.choice([True, False]):
+>>>         payload_dict['response']['body'] = "{}"
+
+
+Let's also randomly return an empty response body. This is tricky middleware indeed. 
+
+::
+
+>>>     print(json.dumps(payload_dict))
+>>> if __name__ == "__main__":
+>>>     main()
+
+
+If is good practice for your client to be able to deal with unexpected data. This is a great example building middleware that'll thoroughly test your apps.
+
+We are now ready to run our payload modification script: ``python examples/modify/modify.py``
+
+Output:
+
+>>> something went wrong - deal with it gracefully
+>>> something went wrong - deal with it gracefully
+>>> something went wrong - deal with it gracefully
+>>> something went wrong - deal with it gracefully
+>>> something went wrong - deal with it gracefully
+>>> response successfully modified, current date is 01:45:15 PM
+>>> something went wrong - deal with it gracefully
+>>> something went wrong - deal with it gracefully
+>>> response successfully modified, current date is 01:45:16 PM
+>>> [...]
+
+Excellent, above we can see how our application now deals with dire responses adequately. This is how resilient software is built! 

examples/modify/modify.py

@@ -1,28 +1,32 @@
-# Demonstrates how to modify requests. This is particularly useful for sending curved
+# Let's look into mutating responses using middleware. This is particularly useful for sending curved
 # balls to your applications, and make sure they deal with them correctly.
-# import hoverpy's main class: HoverPy
 from hoverpy import HoverPy
-
-# import requests for http
 import requests
 
-# create our HoverPy object with modify and middleware enabled.
-# please note this brings in ```python examples/modify/modify_payload.py```
-# which will get run on every request
 with HoverPy(
-    flags=[
-        "-modify",
-        "-middleware",
-        "python examples/modify/modify_payload.py"]) as hoverpy:
-
-    # our middleware is designed to random return an empty body instead of what it's supposed
-    # to return (the curren time). This is a good example of how to alter your dependencies,
-    # and adequately test and react based on their content
+        modify=True,
+        middleware="python examples/modify/modify_payload.py") as hoverpy:
+
+    # Above we created our HoverPy object with modify and middleware enabled.
+    # Please note this brings in ```python examples/modify/modify_payload.py```
+    # which will get run on every request.
+
     for i in range(30):
         r = requests.get("http://time.jsontest.com")
+
+        # let's make 30 requests to time.jsontest.com which simply gets us the
+        # current local time
+
         if "time" in r.json().keys():
             print(
                 "response successfully modified, current date is " +
                 r.json()["time"])
+
+        # time ``time`` key is inside the response, which is what we expected.
+
         else:
             print("something went wrong - deal with it gracefully")
+
+        # however if the ``time`` key isn't in the response, then something
+        # clearly went wrong. Next let's take a look at the middleware.<br><br>
+# .. include:: modify_payload.rst

examples/modify/modify_payload.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python
 
+# This is the payload modification script. It truly allows us to do all
+# types of weird, wild and wonderful mutations to the data that gets sent
+# back to our application. Let's begin by imporing what we'll need.
+
 import sys
 import json
 import logging
@@ -8,24 +12,48 @@
 logging.basicConfig(filename='middleware.log', level=logging.DEBUG)
 logging.debug('Middleware "modify_request" called')
 
+# Above we've also configured our logging. This is essential, as it's
+# difficult to figure out what went wrong otherwise.
+
 
 def main():
     data = sys.stdin.readlines()
-    # this is a json string in one line so we are interested in that one line
     payload = data[0]
     logging.debug(payload)
-
-    logging.debug(payload)
-
     payload_dict = json.loads(payload)
 
+    # The response to our request gets sent to middleware via stdin.
+    # Therefore, we are really only interested in the first line.
+
     payload_dict['response']['status'] = random.choice([200, 201])
 
+    # Let's randomly switch the status for the responses between 200, and 201.
+    # This helps us build a resilient client, that can deal with curved balls.
+
     if random.choice([True, False]):
         payload_dict['response']['body'] = "{}"
 
-    # returning new payload
+    # Let's also randomly return an empty response body. This is tricky
+    # middleware indeed.
     print(json.dumps(payload_dict))
 
 if __name__ == "__main__":
     main()
+# If is good practice for your client to be able to deal with unexpected
+# data. This is a great example building middleware that'll thoroughly
+# test your apps.<br><br>
+# We are now ready to run our payload modification script:
+# ``python examples/modify/modify.py``<br><br>
+# Output:<br><br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> response successfully modified, current date is 01:45:15 PM<br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> something went wrong - deal with it gracefully<br>
+# >>> response successfully modified, current date is 01:45:16 PM<br>
+# >>> [...]<br><br>
+# Excellent, above we can see how our application now deals with dire
+# responses adequately. This is how resilient software is built!

hoverpy/generateDocs.py

@@ -9,6 +9,7 @@ def gen():
         "examples/delays/delays.py",
         "examples/basic/basic.py",
         "examples/modify/modify.py",
+        "examples/modify/modify_payload.py",
         "examples/readthedocs/readthedocs.py",
         "examples/unittesting/unittesting.py",
         "examples/urllib2eg/urllib2eg.py",
@@ -26,7 +27,7 @@ def gen():
             if line == "":
                 continue
             assert(line)
-            lineType = "comment" if re.match("^\s*#", line) else "code"
+            lineType = "comment" if re.match("^\s*# ", line) else "code"
             if lastLineType == "":
                 lastLineType = lineType
             if lineType == "comment":

makefile

@@ -64,6 +64,7 @@ docs: .PHONY
 	mv examples/basic/basic.rst docs/source/
 	mv examples/readthedocs/readthedocs.rst docs/source/
 	mv examples/modify/modify.rst docs/source/
+	mv examples/modify/modify_payload.rst docs/source/
 	mv examples/delays/delays.rst docs/source/
 	mv examples/unittesting/unittesting.rst docs/source/
 	mv examples/urllib2eg/urllib2eg.rst docs/source/