From 0fa9b631c1fd546d3f6e8f41318a45d242eb6151 Mon Sep 17 00:00:00 2001
From: Mike Helmick <mikehelmick@me.com>
Date: Thu, 18 Jul 2013 23:42:52 -0400
Subject: [PATCH] Update documentation for cursor example

[ci skip]
---
 docs/index.rst                   | 24 ++++++++++++++++++
 docs/usage/special_functions.rst | 43 ++++++++++++++++++++++++++++++++
 twython/api.py                   | 18 -------------
 3 files changed, 67 insertions(+), 18 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index e971e45..1aa13e0 100644
--- a/docs/index.rst
+++ b/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
diff --git a/docs/usage/special_functions.rst b/docs/usage/special_functions.rst
index 3d791b6..9f432ee 100644
--- a/docs/usage/special_functions.rst
+++ b/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
 --------------
 
diff --git a/twython/api.py b/twython/api.py
index 6a99a7d..0cabcda 100644
--- a/twython/api.py
+++ b/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,