improve top-level docstring

requests/__init__.py

@@ -6,8 +6,35 @@
 #          /
 
 """
-requests
-~~~~~~~~
+requests HTTP library
+~~~~~~~~~~~~~~~~~~~~~
+
+Requests is an HTTP library, written in Python, for human beings. Basic GET
+usage:
+
+   >>> import requests
+   >>> r = requests.get('http://python.org')
+   >>> r.status_code
+   200
+   >>> 'Python is a programming language' in r.content
+   True
+
+... or POST:
+
+   >>> payload = dict(key1='value1', key2='value2')
+   >>> r = requests.post("http://httpbin.org/post", data=payload)
+   >>> print r.text
+   {
+     // ...snip... //
+     "form": {
+       "key2": "value2",
+       "key1": "value1"
+     },
+     // ...snip... //
+   }
+
+The other HTTP methods are supported - see `requests.api`. Full documentation
+is at <http://requests.rtfd.org/>.
 
 :copyright: (c) 2012 by Kenneth Reitz.
 :license: ISC, see LICENSE for more details.