Add docs for QueryChain

docs/index.rst

@@ -17,4 +17,5 @@ SQLAlchemy-Utils provides custom data types and various utility functions for SQ
    generic_relationship
    database_helpers
    model_helpers
+   utility_classes
    license

docs/utility_classes.rst

@@ -0,0 +1,10 @@
+Utility classes
+===============
+
+QueryChain
+----------
+
+.. module:: sqlalchemy_utils.query_chain
+
+.. autoclass:: QueryChain
+    :members:

sqlalchemy_utils/query_chain.py

@@ -3,19 +3,72 @@ from copy import copy
 
 class QueryChain(object):
     """
+    QueryChain can be used as a wrapper for sequence of queries.
+
+    Features:
+
+        * Easy iteration for sequence of queries
+        * Limit and offset which are smartly applied to all queries
+        * Smart __getitem__ support
+
     :param queries: A sequence of SQLAlchemy Query objects
     :param limit: Similar to normal query limit this parameter can be used for
         limiting the number of results for the whole query chain.
     :param offset: Similar to normal query offset this parameter can be used
         for offsetting the query chain as a whole.
 
+
+    Simple iteration
+    ^^^^^^^^^^^^^^^^
     ::
 
         chain = QueryChain([session.query(User), session.query(Article)])
 
-        for obj in chain[0:5]:
+        for obj in chain:
             print obj
 
+
+    Limit and offset
+    ^^^^^^^^^^^^^^^^
+
+    Lets say you have 5 blog posts, 5 articles and 5 news items in your
+    database.
+
+    ::
+
+        chain = QueryChain(
+            [
+                session.query(BlogPost),
+                session.query(Article),
+                session.query(NewsItem)
+            ],
+            limit=5
+        )
+
+        list(chain)  # all blog posts but not articles and news items
+
+
+        chain.offset = 4
+        list(chain)  # last blog post, and first four articles
+
+
+    Chain slicing
+    ^^^^^^^^^^^^^
+
+    ::
+
+        chain = QueryChain(
+            [
+                session.query(BlogPost),
+                session.query(Article),
+                session.query(NewsItem)
+            ]
+        )
+
+        chain[3:6]   # New QueryChain with offset=3 and limit=6
+
+
+
     .. versionadded: 0.26.0
     """
     def __init__(self, queries, limit=None, offset=None):