Docs: break apart the lengthy readme into organized docs

Also sphinx-ify where appropriate, and lots of general cleanup/editing.

docs/index.rst

@@ -3,20 +3,105 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Djrill's documentation!
-==================================
+Djrill: Mandrill for Django
+===========================
 
-Contents:
+Release |release|
+
+Djrill integrates the `Mandrill <http://mandrill.com>`_ transactional
+email service into Django.
+
+In general, Djrill "just works" with Django's built-in
+`django.core.mail <https://docs.djangoproject.com/en/dev/topics/email/>`_
+functions. It supports:
+
+* HTML email, attachments, extra headers, and other basic email functionality
+* Mandrill-specific extensions like tags, metadata, tracking, and MailChimp templates
+* An optional Django admin interface
+
+Djrill is tested with Django 1.3 and later (including Python 3 support with Django 1.5).
+It is made available under the BSD license.
+
+
+.. _quickstart:
+
+Quick Start
+-----------
+
+1. Install from PyPI:
+
+   .. code-block:: console
+
+    $ pip install djrill
+
+
+2. Edit your project's :file:`settings.py`:
+
+   .. code-block:: python
+
+    INSTALLED_APPS = (
+        ...
+        "djrill"
+    )
+
+    MANDRILL_API_KEY = "<your Mandrill key>"
+    EMAIL_BACKEND = "djrill.mail.backends.djrill.DjrillBackend"
+
+
+3. Now the regular `Django email functions <https://docs.djangoproject.com/en/dev/topics/email/>`_
+   will send through Mandrill::
+
+    from django.core.mail import send_mail
+
+    send_mail("It works!", "This will get sent through Mandrill",
+        "Djrill Sender <djrill@example.com>", ["to@example.com"])
+
+
+   You could send an HTML message, complete with custom Mandrill tags and metadata::
+
+    from django.core.mail import EmailMultiAlternatives
+
+    msg = EmailMultiAlternatives(
+        subject="Djrill Message",
+        body="This is the text email body",
+        from_email="Djrill Sender <djrill@example.com>",
+        to=["Recipient One <someone@example.com>", "another.person@example.com"],
+        headers={'Reply-To': "Service <support@example.com>"} # optional extra headers
+    )
+    msg.attach_alternative("<p>This is the HTML email body</p>", "text/html")
+
+    # Optional Mandrill-specific extensions:
+    msg.tags = ["one tag", "two tag", "red tag", "blue tag"]
+    msg.metadata = {'user_id': "8675309"}
+
+    # Send it:
+    msg.send()
+
+   (Be sure to use a ``from_email`` that's in one of your Mandrill approved sending
+   domains, or the message won't get sent.)
+
+
+Documentation
+-------------
 
 .. toctree::
    :maxdepth: 2
 
+   installation
+   usage/sending_mail
+   usage/templates
+   usage/multiple_backends
+   contributing
+   history
 
 
-Indices and tables
-==================
+Thanks
+------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Thanks to the MailChimp team for asking us to build this nifty little app, and to all of Djrill's
+:doc:`contributors <contributing>`. Also thanks to James Socol on Github for his django-adminplus_
+library that got us off on the right foot for the custom admin views.
+Oh, and, of course, Kenneth Reitz for the awesome requests_ library.
 
+.. _requests: http://docs.python-requests.org
+.. _django-adminplus: https://github.com/jsocol/django-adminplus