Update README.rst

README.rst

@@ -26,14 +26,18 @@ Usage
 
     >>> r = session.get('https://python.org/')
 
+    # Grab a list of all links on the page (anchors excluded). 
     >>> r.html.links
     {'/users/membership/', '/about/gettingstarted/', 'http://feedproxy.google.com/~r/PythonInsider/~3/zVC80sq9s00/python-364-is-now-available.html', '/about/success/', 'http://flask.pocoo.org/', 'http://www.djangoproject.com/', '/blogs/', ... '/psf-landing/', 'https://wiki.python.org/moin/PythonBooks'}
 
+    # Grab a list of all links on the page, in absolute form (anchors excluded).
     >>> r.html.absolute_links
     {'http://feedproxy.google.com/~r/PythonInsider/~3/zVC80sq9s00/python-364-is-now-available.html', 'https://www.python.org/downloads/mac-osx/', 'http://flask.pocoo.org/', 'https://www.python.org//docs.python.org/3/tutorial/', 'http://www.djangoproject.com/', 'https://wiki.python.org/moin/BeginnersGuide', 'https://www.python.org//docs.python.org/3/tutorial/controlflow.html#defining-functions', 'https://www.python.org/about/success/', 'http://twitter.com/ThePSF', 'https://www.python.org/events/python-user-group/634/', ..., 'https://wiki.python.org/moin/PythonBooks'}
 
+    # Select an element with a jQuery selector.
     >>> about = r.html.find('#about')[0]
 
+    # Grab an element's text contents. 
     >>> print(about.text)
     About
     Applications
@@ -42,6 +46,15 @@ Usage
     Help
     Python Brochure
 
+    # Introspect an Element's attributes.
+    >>> about.attrs
+    {'id': 'about', 'class': 'tier-1 element-1  ', 'aria-haspopup': 'true'}
+
+    # Select Elements within Elements. 
+    >>> about.find('a')
+    [<Element 'a' href='/about/' title='' class=''>, <Element 'a' href='/about/apps/' title=''>, <Element 'a' href='/about/quotes/' title=''>, <Element 'a' href='/about/gettingstarted/' title=''>, <Element 'a' href='/about/help/' title=''>, <Element 'a' href='http://brochure.getpython.info/' title=''>]
+
+    # Render an Element as Markdown. 
     >>> print(about.markdown)
 
     * [About](/about/)
@@ -51,13 +64,7 @@ Usage
       * [Getting Started](/about/gettingstarted/)
       * [Help](/about/help/)
       * [Python Brochure](http://brochure.getpython.info/)
-
-    >>> about.attrs
-    {'id': 'about', 'class': 'tier-1 element-1  ', 'aria-haspopup': 'true'}
-
-    >>> about.find('a')
-    [<Element 'a' href='/about/' title='' class=''>, <Element 'a' href='/about/apps/' title=''>, <Element 'a' href='/about/quotes/' title=''>, <Element 'a' href='/about/gettingstarted/' title=''>, <Element 'a' href='/about/help/' title=''>, <Element 'a' href='http://brochure.getpython.info/' title=''>]
-
+      
     >>> r.html.search('Python is a {} language')[0]
     programming