Move sample programs, write new intro

docs/index.rst

@@ -4,11 +4,6 @@
  ElasticUtils
 ==============
 
-ElasticUtils is a Python library that gives you a chainable search API
-for `ElasticSearch <http://elasticsearch.org/>`_ as well as some other
-tools to make it easier to integrate ElasticSearch into your
-application.
-
 :Version:       |release|
 :Code:          https://github.com/mozilla/elasticutils
 :License:       BSD; see LICENSE file
@@ -17,6 +12,63 @@ application.
 :IRC:           #elasticutils on irc.mozilla.org
 
 
+ElasticUtils is a Python library that gives you a chainable search API
+for `ElasticSearch <http://elasticsearch.org/>`_ as well as some other
+tools to make it easier to integrate ElasticSearch into your
+application.
+
+So what's it like? Let's do a couple basic things:
+
+Create an instance of :py:class:`elasticutils.S` and tell it which
+index and doctype to look at.
+
+>>> from elasticutils import S, F
+>>> s = S().indexes('blog-index').doctypes('blog-entry')
+
+Print the count of everything in that index with that type:
+
+>>> print s.count()
+4
+
+Show titles of all blog entries with "elasticutils" in the title:
+
+>>> s = s.query(title__match='elasticutils')
+>>> [result['title'] for result in s]
+[u'ElasticUtils v0.4 released!', u'elasticutils status -- May 18th, 2012',
+u'ElasticUtils sprint at PyCon US 2013']
+
+Use properties rather than keys:
+
+>>> [result.title for result in s]
+[u'ElasticUtils v0.4 released!', u'elasticutils status -- May 18th, 2012',
+u'ElasticUtils sprint at PyCon US 2013']
+
+Filter out entries related to PyCon:
+
+>>> s = s.filter(~F(tag='pycon'))
+>>> [result['title'] for result in s]
+[u'ElasticUtils v0.4 released!', u'elasticutils status -- May 18th, 2012']
+
+Show only the top result:
+
+>>> s = s[:1]
+>>> [result['title'] for result in s]
+[u'ElasticUtils v0.4 released!']
+
+That's the gist of it!
+
+
+Project
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   changelog
+   theory
+   resources
+
+
 .. _users-guide:
 
 User's Guide
@@ -25,15 +77,11 @@ User's Guide
 .. toctree::
    :maxdepth: 1
 
-   changelog
    installation
-   quickstart
-   theory
    queries
    es
    debugging
    api
-   resources
 
 
 Using ElasticUtils with Django
@@ -66,7 +114,8 @@ Sample programs
 .. toctree::
    :maxdepth: 1
 
-   sampleprogram1
+   sampleprogram
+   sampleprogramfacets
 
 
 Indices and tables

docs/quickstart.rst → docs/sampleprogram.rst

@@ -1,9 +1,6 @@
-============
- Quickstart
-============
-
-Sample program
-==============
+======================
+ Basic sample program
+======================
 
 Here's a short script that gives you the gist of how to use
 ElasticUtils:

docs/sampleprogramfacets.rst

@@ -0,0 +1,7 @@
+=============================
+ Sample program using facets
+=============================
+
+.. literalinclude:: samples/sample_facets.py
+   :language: python
+   :linenos: