Update README with examples

README.rst

@@ -1,23 +1,53 @@
-==============
 More Itertools
 ==============
 
 .. image:: https://coveralls.io/repos/github/erikrose/more-itertools/badge.svg?branch=master
   :target: https://coveralls.io/github/erikrose/more-itertools?branch=master
 
-I love itertools; it's one of the most beautiful, composable standard libs.
-Whenever I have an iteration problem, there's almost always an itertools
-routine that fits it perfectly. Sometimes, however, neither itertools nor the
-recipes included in its docs do quite what I need.
+Python's ``itertools`` library is a gem - you can compose elegant solutions
+for a variety of problems with the functions it provides. In ``more-itertools``
+we collect additional building blocks, recipes, and routines for working with
+Python iterables.
+
+Getting started
+===============
+
+To get started, install the library with `pip <https://pip.pypa.io/en/stable/>`_:
+
+.. code-block:: shell
+
+    pip install more-itertools
+
+The recipes from the `itertools docs <https://docs.python.org/3/library/itertools.html>`_
+are included in the top-level package:
+
+.. code-block:: python
+
+    >>> from more_itertools import flatten
+    >>> iterable = [(0, 1), (2, 3)]
+    >>> list(flatten(iterable))
+    [0, 1, 2, 3]
+
+Several new recipes are available as well:
+
+.. code-block:: python
+
+    >>> from more_itertools import spy, chunked
+    >>> iterable = [0, 1, 2, 3, 4, 5, 6, 7]
+    >>> head, iterable = spy(iterable, n=2)
+    >>> head
+    [0, 1]
+    >>> list(chunked(iterable, 3))
+    [[0, 1, 2], [3, 4, 5], [6, 7]]
+
+For the full listing of functions, see the API documentation at `more-itertools.readthedocs.io <https://more-itertools.readthedocs.io/en/latest/api.html>`_.
 
-Here I've collected several routines I've reached for but not found. Since
-they are deceptively tricky to get right, I've wrapped them up into a library.
-We've also included implementations of the recipes from the itertools
-documentation. Enjoy! Any additions are welcome; just file a pull request.
+Development
+===========
 
+``more-itertools`` is maintained by `@erikrose <https://github.com/erikrose>`_
+and `@bbayles <https://github.com/bbayles>`_, with help from `many others <https://github.com/erikrose/more-itertools/graphs/contributors>`_.
+If you have a problem or suggestion, please file a bug or pull request in this
+repository - thanks for contributing!
 
-Full Documentation
-==================
 
-Please see https://more-itertools.readthedocs.io/en/latest/api.html for the
-list of routines.