From e0d0c40e05855eb12767fc3ee1d1719ae9b37e85 Mon Sep 17 00:00:00 2001
From: RussellBallestrini <devnull@localhost>
Date: Tue, 8 Jan 2013 22:05:26 -0500
Subject: [PATCH] More Documentation in README

---
 README.rst | 69 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 16 deletions(-)

diff --git a/README.rst b/README.rst
index 0a75387..78be2cd 100644
--- a/README.rst
+++ b/README.rst
@@ -19,7 +19,26 @@ The ago module comes with three functions:
 #. delta2human
 #. delta2dict
 
-You really only need to worry about *human*::
+You really only need to worry about *human*.
+
+Here are all the available arguments and defaults::
+
+ human(d, precision=2, format_past='{0} ago', format_future='in {0}'):
+
+d
+ datetime object to make into human readable, required
+
+precision
+ control how verbose the output should look, optional
+
+format_past
+ format string used when d is a past datetime, optional
+
+format_future
+ format string used when d is a future datetime, optional
+
+
+Here is an example on how to use *human*::
 
  from ago import human, delta2human, delta2dict
  
@@ -38,34 +57,53 @@ You really only need to worry about *human*::
   )
 
  # to find out how long ago, use the human function
- print 'Created ' + human( db_date ) + ' ago.'
+ print 'Created ' + human( db_date )
  
  # optionally pass a precision
- print 'Created ' + human( db_date, 3 ) + ' ago.'
- print 'Created ' + human( db_date, 6 ) + ' ago.'
+ print 'Created ' + human( db_date, 3 )
+ print 'Created ' + human( db_date, 6 )
 
 We also support future dates and times::
 
- present = datetime.now()
- past = present - timedelta( 492, 58711, 45 ) # days, secs, ms
- future = present + timedelta( 2, 12447, 963 ) # days, secs, ms
+ PRESENT = datetime.now()
+ PAST = present - timedelta( 492, 58711, 45 ) # days, secs, ms
+ FUTURE = present + timedelta( 2, 12447, 963 ) # days, secs, ms
 
- print 'Shutdown in ' + human( future )
+ print human( FUTURE )
 
 Now we will document how to use delta2human and delta2dict::
 
- # pretend we already have a timedelta object
-
  # subtract two datetime objects for a timedelta object
- d2 = datetime.now()
- delta = d2 - d1
+ delta = PRESENT - db_date
 
  # display a human readable timedelta from a timedelta 
- print 'Created ' + delta2human( delta ) + ' ago.'
+ print 'Created ' + delta2human( delta )
 
  # create a dictionary out of the timedelta
- delta_dict = delta2dict( delta )
- print delta_dict
+ print delta2dict( delta )
+
+Example format_past and format_future keyword arguments::
+
+ output1 = human( PAST,
+   format_past = 'titanic sunk {0} ago',
+   format_future = 'titanic will sink in {0} from now'
+ )
+
+ output2 = human( FUTURE,
+   format_past = 'titanic sunk {0} ago',
+   format_future = 'titanic will sink in {0} from now'
+ )
+
+ print output1
+ # titanic sunk 1 year, 127 days ago
+ print output2
+ # titanic will sink in 2 days, 3 hours from now
+
+
+Need more examples?
+==========================
+
+You should look at test_ago.py
 
 
 How do I thank you?
@@ -80,7 +118,6 @@ License
 Public Domain
 
 
-
 Public Revision Control
 ==============================