Issue 54. Add docs for order-by

This also adds API documentation. It's not great because the docstrings
need work, but it's better!

docs/es.rst

@@ -12,7 +12,7 @@ To access this, you use `get_es()` which builds an `ES`.
 
 .. Warning::
 
-   ElasticUtils works best with ``pyes`` 0.15 and 0.16. The API for
-   later versions has changed too drastically. While we'd welcome
-   compatibility patches, we feel a better approach would be to remove
-   our dependency on ``pyes``.
+   ElasticUtils works with ``pyes`` 0.15 and 0.16. The API for later
+   versions of pyes has changed too much and won't work with
+   ElasticUtils. We're planning to switch to something different in
+   the future.

docs/queries.rst

@@ -455,6 +455,29 @@ only to that field name and field action. For example::
 will only apply the 4.0 boost to ``title__prefix``.
 
 
+Ordering
+========
+
+You can order search results by specified fields::
+
+    q = (S().query(title='trucks')
+            .order_by('title')
+
+This orders search results by the `title` field in ascending order.
+
+If you want to sort by descending order, prepend a ``-``::
+
+    q = (S().query(title='trucks')
+            .order_by('-title')
+
+You can also sort by the computed field ``_score``.
+
+.. seealso::
+
+   http://www.elasticsearch.org/guide/reference/api/search/sort.html
+     ElasticSearch docs on sort parameter in the Search API
+
+
 Demoting
 ========
 
@@ -909,3 +932,62 @@ This works regardless of what form the search results are in.
    http://www.elasticsearch.org/guide/reference/api/search/explain.html
      ElasticSearch docs on explain (which are pretty bereft of
      details).
+
+
+API
+===
+
+The S class
+-----------
+
+.. autoclass:: elasticutils.S
+
+   .. automethod:: elasticutils.S.__init__
+
+   **Chaining transforms**
+
+       .. automethod:: elasticutils.S.query
+
+       .. automethod:: elasticutils.S.filter
+
+       .. automethod:: elasticutils.S.order_by
+
+       .. automethod:: elasticutils.S.boost
+
+       .. automethod:: elasticutils.S.demote
+
+       .. automethod:: elasticutils.S.facet
+
+       .. automethod:: elasticutils.S.facet_raw
+
+       .. automethod:: elasticutils.S.highlight
+
+       .. automethod:: elasticutils.S.values_list
+
+       .. automethod:: elasticutils.S.values_dict
+
+       .. automethod:: elasticutils.S.es
+
+       .. automethod:: elasticutils.S.es_builder
+
+       .. automethod:: elasticutils.S.indexes
+
+       .. automethod:: elasticutils.S.doctypes
+
+       .. automethod:: elasticutils.S.explain
+
+   **Methods to override if you need different behavior**
+
+       .. automethod:: elasticutils.S.get_es
+
+       .. automethod:: elasticutils.S.get_indexes
+
+       .. automethod:: elasticutils.S.get_doctypes
+
+   **Methods that force evaluation**
+
+       .. automethod:: elasticutils.S.count
+
+       .. automethod:: elasticutils.S.facet_counts
+
+

elasticutils/__init__.py

@@ -39,15 +39,23 @@ def get_es(hosts=None, default_indexes=None, timeout=None, dump_curl=None,
 
     Examples:
 
-    >>> get_es()
-    >>> get_es(hosts=['localhost:9200'])
-    >>> get_es(timeout=30)  # good for indexing
-    >>> get_es(default_indexes=['sumo_prod_20120627']
+    >>> es = get_es()
+
+
+    >>> es = get_es(hosts=['localhost:9200'])
+
+
+    >>> es = get_es(timeout=30)  # good for indexing
+
+
+    >>> es = get_es(default_indexes=['sumo_prod_20120627']
+
+
     >>> class CurlDumper(object):
     ...     def write(self, text):
     ...         print text
     ...
-    >>> get_es(dump_curl=CurlDumper())
+    >>> es = get_es(dump_curl=CurlDumper())
 
     """
     # Cheap way of de-None-ifying things
@@ -205,9 +213,18 @@ def _boosted_value(name, action, key, value, boost):
 
 
 class S(object):
-    """
-    Represents a lazy ElasticSearch lookup, with a similar api to
-    Django's QuerySet.
+    """Represents a lazy ElasticSearch Search API request.
+
+    The API for `S` takes inspiration from Django's QuerySet.
+
+    `S` can be either typed or untyped. An untyped `S` returns dict
+    results by default.
+
+    An `S` is lazy in the sense that it doesn't do an ElasticSearch
+    search request until it's forced to evaluate by either iterating
+    over it, calling ``.count``, doing ``len(s)``, or calling
+    ``.facet_count``.
+
     """
     def __init__(self, type_=None):
         """Create and return an S.
@@ -246,7 +263,7 @@ def es(self, **settings):
         the search.
 
         :arg settings: the settings you'd use to build the ES---same
-            as what you'd pass to :fun:`get_es`.
+            as what you'd pass to :py:func:`get_es`.
 
         """
         return self._clone(next_step=('es', settings))