From 695d531064277978d44f78387a3edb3d29fb6f25 Mon Sep 17 00:00:00 2001
From: Harmon <Harmon758@gmail.com>
Date: Mon, 12 Apr 2021 22:02:24 -0500
Subject: [PATCH] Document pagination

---
 docs/index.rst       |  1 +
 docs/pagination.rst  | 30 ++++++++++++++++++++++++++++++
 tweepy/pagination.py | 19 +++++++++++++++++++
 3 files changed, 50 insertions(+)
 create mode 100644 docs/pagination.rst

diff --git a/docs/index.rst b/docs/index.rst
index 279cd8d..f5109e3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,6 +22,7 @@ Contents:
    stream.rst
    exceptions.rst
    extended_tweets.rst
+   pagination.rst
    streaming.rst
    running_tests.rst
    changelog.md
diff --git a/docs/pagination.rst b/docs/pagination.rst
new file mode 100644
index 0000000..132860d
--- /dev/null
+++ b/docs/pagination.rst
@@ -0,0 +1,30 @@
+.. _pagination_guide:
+
+.. currentmodule:: tweepy
+
+**********
+Pagination
+**********
+
+API v2
+======
+
+.. autoclass:: Paginator
+    :members:
+
+Example
+-------
+
+::
+
+    import tweepy
+
+    client = tweepy.Client("Bearer Token here")
+
+    for response in tweepy.Paginator(client.get_users_followers, 2244994945,
+                                     max_results=1000, limit=5):
+        print(response.meta)
+
+    for tweet in tweepy.Paginator(client.search_recent_tweets, "Tweepy",
+                                  max_results=100).flatten(limit=250):
+        print(tweet.id)
diff --git a/tweepy/pagination.py b/tweepy/pagination.py
index 39ff842..6e9fd47 100644
--- a/tweepy/pagination.py
+++ b/tweepy/pagination.py
@@ -6,6 +6,18 @@ from math import inf
 
 
 class Paginator:
+    """:class:`Paginator` can be used to paginate for any :class:`Client`
+    methods that support pagination
+
+    Parameters
+    ----------
+    method
+        :class:`Client` method to paginate for
+    args
+        Positional arguments to pass to ``method``
+    kwargs
+        Keyword arguments to pass to ``method``
+    """
 
     def __init__(self, method, *args, **kwargs):
         self.method = method
@@ -20,6 +32,13 @@ class Paginator:
                                   **self.kwargs)
 
     def flatten(self, limit=inf):
+        """Flatten paginated data
+
+        Parameters
+        ----------
+        limit
+            Maximum number of results to yield
+        """
         if limit <= 0:
             return
 
-- 
2.25.1