Update documentation for cursor example

[ci skip]

docs/index.rst

@@ -29,14 +29,38 @@ Features
 Usage
 -----
 
+..
+   I know it isn't necessary to start a new tree for every section,
+   but I think it looks a bit cleaner that way!
+
 .. toctree::
    :maxdepth: 4
 
    usage/install
+
+.. toctree::
+   :maxdepth: 4
+
    usage/starting_out
+
+.. toctree::
+   :maxdepth: 4
+
    usage/basic_usage
+
+.. toctree::
+   :maxdepth: 4
+
    usage/advanced_usage
+
+.. toctree::
+   :maxdepth: 4
+
    usage/streaming_api
+
+.. toctree::
+   :maxdepth: 2
+
    usage/special_functions
 
 Twython API Documentation

docs/usage/special_functions.rst

@@ -7,6 +7,49 @@ This section covers methods to are part of Twython but not necessarily connected
 
 *******************************************************************************
 
+Cursor
+------
+
+This function returns a generator for Twitter API endpoints that are able to be pagintated in some way (either by cursor or since_id parameter)
+
+The Old Way
+^^^^^^^^^^^
+
+.. code-block:: python
+
+    from twython import Twython
+
+    twitter = Twython(APP_KEY, APP_SECRET,
+                      OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
+
+    results = twitter.search(q='twitter')
+    if results.get('statuses'):
+        for result in results['statuses']:
+            print result['id_str']
+
+The New Way
+^^^^^^^^^^^
+
+.. code-block:: python
+
+    from twython import Twython
+
+    twitter = Twython(APP_KEY, APP_SECRET,
+                      OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
+
+    results = twitter.cursor(t.search, q='twitter')
+    for result in results:
+        print result['id_str']
+
+Another example:
+
+.. code-block:: python
+
+    results = twitter.cursor(t.get_mentions_timeline)
+    for result in results:
+        print result['id_str']
+
+
 HTML for Tweet
 --------------
 

twython/api.py

@@ -363,24 +363,6 @@ class Twython(EndpointsMixin, object):
         return '%s?%s' % (api_url, '&'.join(querystring))
 
     def search_gen(self, search_query, **params):  # pragma: no cover
-        """Returns a generator of tweets that match a specified query.
-
-        Documentation: https://dev.twitter.com/docs/api/1.1/get/search/tweets
-
-        :param search_query: Query you intend to search Twitter for
-        :param \*\*params: Extra parameters to send with your search request
-        :rtype: generator
-
-        Usage::
-
-          >>> from twython import Twython
-          >>> twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
-
-          >>> search = twitter.search_gen('python')
-          >>> for result in search:
-          >>>   print result
-
-        """
         warnings.warn(
             'This method is deprecated. You should use Twython.cursor instead. [eg. Twython.cursor(Twython.search, q=\'your_query\')]',
             TwythonDeprecationWarning,