Start writing the documentation

 * add bootstrap theme and configuration
 * update the synopsis for HTTPClient
 * start to write a tutorial on how to use the library and how to write tests
   with a custom useragent

docs/conf.py

@@ -16,6 +16,7 @@
     import http
 except ImportError:
     sys.path.append(os.path.abspath('../'))
+    sys.path.append(os.path.abspath('_themes'))
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -95,7 +96,8 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme_path = ['_themes']
+html_theme = 'bootstrap'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/httpclient.rst

@@ -8,11 +8,23 @@ HTTPClient
 Synopsis
 --------
 
+::
+
+   >>> from http import Request
+   >>> from httpclient import HTTPClient
+   >>> request = Request('GET', 'http://lumberjaph.net')
+   >>> client = HTTPClient()
+   >>> client.request(request)
+   >>> response = client.request(request)
+   >>> print response.status
+   200
+
+
 Interface
 ---------
 
 :class:`HTTPClient` instances have the following methods:
 
 .. autoclass:: HTTPClient()
    :members:
-   :undoc-members:
+   :undoc-members:

docs/index.rst

@@ -9,10 +9,10 @@ This module is heavily inspired by LWP::UserAgent
 
     >>> from httpclient import HTTPClient
     >>> from http import Request
-    >>> r = Request('GET', 'http://lumberjaph.net')
-    >>> c = HTTPClient()
-    >>> resp = c.request(r)
-    >>> print resp.status
+    >>> request = Request('GET', 'http://lumberjaph.net')
+    >>> cclient = HTTPClient()
+    >>> response = cclient.request(request)
+    >>> print response.status
     200
 
 User Guide

docs/tutorial.rst

@@ -14,4 +14,79 @@ Then a Request object is created. The request is then passed to the client, whic
 
 The default client will set the timeout to 60 seconds, the useragent string to 'python-http', and the number of redirection to follow to 7.
 
-    >>> client = Client(agent='my uber application', timeout=10)
+    >>> client = Client(agent='my uber application', timeout=10)
+
+How to use this library
+-----------------------
+
+For the purpose of this documentation, let's start with a simple client for the GitHub API.
+
+::
+
+    from httpclient import HTTPClient
+    from http import Request, Url
+    import json
+
+
+    class GitHubClient(object):
+
+        def __init__(self, user_agent=None, base_url='https://api.github.com'):
+            self.base_url = base_url
+            if user_agent is None:
+                self._user_agent = HTTPClient()
+            else:
+                self._user_agent = user_agent
+
+        @property
+        def user_agent(self):
+            return self._user_agent
+
+        @user_agent.setter
+        def user_agent(self, user_agent):
+            self._user_agent = user_agent
+
+        def get_user(self, username):
+            endpoint = Url(self.base_url)
+            endpoint.path.append('users')
+            endpoint.path.append(username)
+            request = Request('GET', endpoint)
+            response = self.user_agent.request(request)
+            if response.is_success:
+                return json.loads(response.content)
+            else:
+                raise Exception(response.status_line)
+
+::
+
+    >>> gh = GitHubClient()
+    >>> res = gh.get_user('franckcuny')
+    >>> print res['name']
+    'franck'
+
+Setting the useragent
+~~~~~~~~~~~~~~~~~~~~~
+
+You should let the possibility for the developper to set its own ``user_agent``.
+
+How to test
+-----------
+
+Now, we will add tests for this client.
+
+::
+
+    def _cb(request):
+        response = Response(200, content=json.dumps({'name': 'batman'}))
+        return response
+    
+    
+    class Test(unittest.TestCase):
+    
+        def testName(self):
+            ua = HTTPClient()
+            ua.add_handler('request_send', _cb)
+            client = GitHubClient(user_agent=ua)
+            res = client.get_user('franckcuny')
+            self.assertEqual(res['name'], 'batman')
+            
+If we execute these test, the callback ``cb`` will be called, and since it returns a class:``Response`` object, the request is never sent over the wire.