From c3e1774019da673baa15cfd7fa67e558ef707e99 Mon Sep 17 00:00:00 2001
From: Konsta Vesterinen <konsta.vesterinen@gmail.com>
Date: Tue, 6 May 2014 14:45:10 +0300
Subject: [PATCH] Add docs for QueryChain

---
 docs/index.rst                  |  1 +
 docs/utility_classes.rst        | 10 ++++++
 sqlalchemy_utils/query_chain.py | 55 ++++++++++++++++++++++++++++++++-
 3 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 docs/utility_classes.rst

diff --git a/docs/index.rst b/docs/index.rst
index 943179b..33463bd 100644
--- a/docs/index.rst
+++ b/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
diff --git a/docs/utility_classes.rst b/docs/utility_classes.rst
new file mode 100644
index 0000000..3764973
--- /dev/null
+++ b/docs/utility_classes.rst
@@ -0,0 +1,10 @@
+Utility classes
+===============
+
+QueryChain
+----------
+
+.. module:: sqlalchemy_utils.query_chain
+
+.. autoclass:: QueryChain
+    :members:
diff --git a/sqlalchemy_utils/query_chain.py b/sqlalchemy_utils/query_chain.py
index e0eb308..20ecfbd 100644
--- a/sqlalchemy_utils/query_chain.py
+++ b/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):