DRY up duplicate content in the readme and docs index page.

* Don't maintain similar overview in README.rst and docs/index.rst -- instead just include relevant portions of readme in the docs
* Patch up README version numbers and doc links in setup.py long_description to freeze them to the version being setup
* Suppress the Travis build status indicator in the docs and PyPI, since it can't be frozen to the specific version in question

README.rst

@@ -1,23 +1,121 @@
-Djrill: Mandrill for Django
+..  This README is reused in multiple places:
-===========================
+    * Github: project page, exactly as it appears here
+    * Docs: shared-intro section gets included in docs/index.rst
+            quickstart section gets included in docs/quickstart.rst
+    * PyPI: project page (via setup.py long_description),
+            with several edits to freeze it to the specific PyPI release
+            (see long_description_from_readme in setup.py)
+    You can use docutils 1.0 markup, but *not* any Sphinx additions.
+
+.. These substitution definitions apply in the readme (github) only;
+   they're altered by setup.py for the long_description,
+   and defined differently for the docs includes
+
+.. |release| replace:: (source)
+
+.. |version| replace:: |release|
+
+.. |buildstatus| image:: https://secure.travis-ci.org/brack3t/Djrill.png?branch=master
+                 :target: https://travis-ci.org/brack3t/Djrill
+
+.. default-role:: literal
+
+
+.. _shared-intro:
+   .. This shared-intro section is also included in docs/index.rst
+
+Djrill: Mandrill Transactional Email for Django
+===============================================
+
+Release |release|
 
 Djrill integrates the `Mandrill <http://mandrill.com>`_ transactional
 email service into Django.
 
-In general, Djrill "just works" with Django's built-in
+In general, Djrill "just works" with Django's built-in `django.core.mail`
-`django.core.mail <https://docs.djangoproject.com/en/dev/topics/email/>`_
+package. It includes:
-functions. It supports:
 
-* HTML email, attachments, extra headers, and other basic email functionality
+* Support for HTML, attachments, extra headers, and other features of
+  `Django's built-in email <https://docs.djangoproject.com/en/dev/topics/email/>`_
 * Mandrill-specific extensions like tags, metadata, tracking, and MailChimp templates
 * An optional Django admin interface
 
-.. image:: https://secure.travis-ci.org/brack3t/Djrill.png?branch=master
+Djrill is released under the BSD license. It is tested against Django 1.3, 1.4, and 1.5
-:target: https://travis-ci.org/brack3t/Djrill
+(including Python 3 support with Django 1.5). |buildstatus|
 
-Djrill is tested with Django 1.3 and later (including Python 3 support with Django 1.5).
+.. END shared-intro
-It is made available under the BSD license.
 
-* Documentation: https://readthedocs.org/docs/djrill/en/latest/
+Resources:
+
+* Full documentation: https://djrill.readthedocs.org/en/latest/
 * Package on PyPI: https://pypi.python.org/pypi/djrill
-* Latest source: https://github.com/brack3t/Djrill
+* Project on Github: https://github.com/brack3t/Djrill
+
+
+Djrill 1-2-3
+------------
+
+.. _quickstart:
+   .. This quickstart section is also included in docs/quickstart.rst
+
+1. Install Djrill from PyPI:
+
+   .. code-block:: console
+
+        $ pip install djrill
+
+
+2. Edit your project's ``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:
+
+   .. code-block:: python
+
+        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:
+
+   .. code-block:: python
+
+        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.)
+
+.. END quickstart
+
+
+See the `full documentation <https://djrill.readthedocs.org/en/latest/>`_
+for more features and options.

docs/index.rst

@@ -3,83 +3,20 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Djrill: Mandrill for Django
+.. Incorporate the shared-intro section from the root README:
-===========================
 
-Release |release|
+.. include:: ../README.rst
+   :start-after: _shared-intro:
+   :end-before:  END shared-intro
 
-Djrill integrates the `Mandrill <http://mandrill.com>`_ transactional
+.. Eliminate the README's Travis build status indicator.
-email service into Django.
+   (Is there some way we could link to Travis status for the
+   specific |VERSION| of the app being documented here???)
 
-In general, Djrill "just works" with Django's built-in
+.. |buildstatus| replace:: \
-`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:
+.. _toc:
-
-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
 -------------
@@ -87,6 +24,7 @@ Documentation
 .. toctree::
    :maxdepth: 2
 
+   quickstart
    installation
    usage/sending_mail
    usage/templates

docs/quickstart.rst

@@ -0,0 +1,9 @@
+Djrill 1-2-3
+============
+
+.. Quickstart is maintained in README.rst at the source root.
+   (Docs can include from the readme; the readme can't include anything.)
+
+.. include:: ../README.rst
+   :start-after: _quickstart:
+   :end-before:  END quickstart

setup.py

@@ -1,15 +1,26 @@
 from setuptools import setup
-execfile('djrill/_version.py')
+import re
+execfile('djrill/_version.py')  # defines __version__, __minor_version__
 
-with open('LICENSE') as file:
+
-    license_text = file.read()
+def long_description_from_readme(rst):
-with open('README.rst') as file:
+    # Patch up some rest substitution variables (references only - not definitions):
-    long_description = file.read()
+    rst = re.sub(r'(?<!\.\. )\|release\|', __version__, rst)
+    rst = re.sub(r'(?<!\.\. )\|version\|', __minor_version__, rst)
+    rst = re.sub(r'(?<!\.\. )\|buildstatus\|', "", rst)  # hide latest-code Travis status indicator
+    rst = re.sub(r'(djrill\.readthedocs\.org/\w+)/latest',
+                 r'\1/' + __version__, rst)  # freeze docs link to this version
+    return rst
+
+with open('LICENSE') as f:
+    license_text = f.read()
+with open('README.rst') as f:
+    long_description = long_description_from_readme(f.read())
 
 setup(
     name="djrill",
     version=__version__,
-    description='Django email backend for Mandrill.',
+    description='Mandrill transactional email for Django',
     keywords="django, mailchimp, mandrill, email, email backend",
     author="Kenneth Love <kenneth@brack3t.com>, Chris Jones <chris@brack3t.com>",
     author_email="kenneth@brack3t.com",