expand docs

Author: jmcarp

README.rst

@@ -41,9 +41,10 @@ Homepage: `http://pyrobot.readthedocs.org/ <http://pyrobot.readthedocs.org/>`_
     lyrics.text     # \n[Verse 1]\nYou suck my blood like a leech...
 
 PyRobot combines the best of two excellent Python libraries: 
-Requests and BeautifulSoup. PyRobot represents browser sessions using
-Requests and HTML responses using BeautifulSoup, transparently exposing 
-methods of both libraries:
+`Requests <http://docs.python-requests.org/en/latest/>`_ and 
+`BeautifulSoup <http://www.crummy.com/software/BeautifulSoup/>`_. 
+PyRobot represents browser sessions using Requests and HTML responses 
+using BeautifulSoup, transparently exposing methods of both libraries:
 
 .. code-block:: python
 
@@ -67,3 +68,32 @@ methods of both libraries:
                                                         # <span class="mega-octicon octicon-checklist"></span>
                                                         # ...
 
+PyRobot also includes tools for working with forms, inspired by
+`WebTest <https://github.com/Pylons/webtest>`_ and `Mechanize <http://wwwsearch.sourceforge.net/mechanize/>`_.
+
+.. code-block:: python
+    
+    from pyrobot import Browser
+    browser = RoboBrowser()
+
+    # Get the signup form
+    signup_form = browser.get_form(class_='signup')
+    signup_form                     # <RoboForm user[name]=, user[email]=, ...
+
+    # Inspect its values
+    signup_form['authenticity_token'].value     # 6d03597 ...
+
+    # Fill it out
+    signup_form['user[name]'] = 'python-robot'
+    signup_form['user[user_password]'] = 'secret'
+
+    # Serialize it to JSON
+    signup_form.serialize()         # {'data': {'authenticity_token': '6d03597...',
+                                    #  'context': '',
+                                    #  'user[email]': '',
+                                    #  'user[name]': 'python-robot',
+                                    #  'user[user_password]': ''}}   
+
+    # And submit
+    browser.submit_form(signup_form)
+