clean up RST for PyPI, add some better annotations to examples

1 files changed, 37 insertions, 5 deletions

diff --git a/README.rst b/README.rst
index b9f2229..a4087df 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,4 @@
-Retrying, to retry all the things
+Retrying
 =========================
 
 
@@ -58,7 +58,7 @@ But, you might regret that later.
 Examples
 ----------
 
-Here are some snippets and parameters for building your own versions of retrying behavior:
+As you saw above, the default behavior is to retry forever without waiting.
 
 .. code-block:: python
 
@@ -66,26 +66,53 @@ Here are some snippets and parameters for building your own versions of retrying
     def never_give_up_never_surrender():
         print "Retry forever ignoring Exceptions, don't wait between retries"
 
+
+Let's be a little less persistent and set some boundaries, such as the number of attempts before giving up.
+
+.. code-block:: python
+
     @retry(stop='stop_after_attempt', stop_max_attempt_number=7)
     def stop_after_7_attempts():
         print "Stopping after 7 attempts"
 
+We don't have all day, so let's set a boundary for how long we should be retrying stuff.
+
+.. code-block:: python
+
     @retry(stop='stop_after_delay', stop_max_delay=10000)
     def stop_after_10_s():
         print "Stopping after 10 seconds"
 
+Most things don't like to be polled as fast as possible, so let's just wait 2 seconds between retries.
+
+.. code-block:: python
+
     @retry(wait='fixed_sleep', wait_fixed=2000)
     def wait_2_s():
         print "Wait 2 second between retries"
 
+
+Some things perform best with a bit of randomness injected.
+
+.. code-block:: python
+
     @retry(wait='random_sleep', wait_random_min=1000, wait_random_max=2000)
     def wait_random_1_to_2_s():
         print "Randomly wait 1 to 2 seconds between retries"
 
+Then again, it's hard to beat exponential backoff when retrying distributed services and other remote endpoints.
+
+.. code-block:: python
+
     @retry(wait='exponential_sleep', wait_exponential_multiplier=1000, wait_exponential_max=10000)
     def wait_exponential_1000():
         print "Wait 2^x * 1000 milliseconds between each retry, up to 10 seconds, then 10 seconds afterwards"
 
+
+We have a few options for dealing with retries that raise specific or general exceptions, as in the cases here.
+
+.. code-block:: python
+
     def retry_if_io_error(exception):
         """Return True if we should retry (in this case when it's an IOError), False otherwise"""
         return isinstance(exception, IOError)
@@ -94,6 +121,14 @@ Here are some snippets and parameters for building your own versions of retrying
     def might_io_error():
         print "Retry forever with no wait if an IOError occurs, raise any other errors"
 
+    @retry(retry_on_exception=retry_if_io_error, wrap_exception=True)
+    def only_raise_retry_error_when_not_io_error():
+        print "Retry forever with no wait if an IOError occurs, raise any other errors wrapped in RetryError"
+
+We can also use the result of the function to alter the behavior of retrying.
+
+.. code-block:: python
+
     def retry_if_result_none(result):
         """Return True if we should retry (in this case when result is None), False otherwise"""
         return result is None
@@ -102,9 +137,6 @@ Here are some snippets and parameters for building your own versions of retrying
     def might_return_none():
         print "Retry forever ignoring Exceptions with no wait if return value is None"
 
-    @retry(retry_on_exception=retry_if_io_error, wrap_exception=True)
-    def only_raise_retry_error_when_not_io_error():
-        print "Retry forever with no wait if an IOError occurs, raise any other errors wrapped in RetryError"
 
 Any combination of stop, wait, etc. are also supported to give you the freedom to mix and match.