From ea72b2d79034e97e567e8e2d676b5383d6b05bc4 Mon Sep 17 00:00:00 2001 From: medmunds Date: Mon, 4 Mar 2013 19:09:13 -0800 Subject: [PATCH] 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 | 122 +++++++++++++++++++++++++++++++++++++++----- docs/index.rst | 82 ++++------------------------- docs/quickstart.rst | 9 ++++ setup.py | 23 ++++++--- 4 files changed, 146 insertions(+), 90 deletions(-) create mode 100644 docs/quickstart.rst diff --git a/README.rst b/README.rst index ed6d66b..2f259df 100644 --- a/README.rst +++ b/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 `_ transactional email service into Django. -In general, Djrill "just works" with Django's built-in -`django.core.mail `_ -functions. It supports: +In general, Djrill "just works" with Django's built-in `django.core.mail` +package. It includes: -* 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 `_ * 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 -:target: https://travis-ci.org/brack3t/Djrill +Djrill is released under the BSD license. It is tested against Django 1.3, 1.4, and 1.5 +(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). -It is made available under the BSD license. +.. END shared-intro -* 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 = "" + EMAIL_BACKEND = "djrill.mail.backends.djrill.DjrillBackend" + + +3. Now the regular `Django email functions `_ + 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 ", ["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 ", + to=["Recipient One ", "another.person@example.com"], + headers={'Reply-To': "Service "} # optional extra headers + ) + msg.attach_alternative("

This is the HTML email body

", "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 `_ +for more features and options. diff --git a/docs/index.rst b/docs/index.rst index 896d4e6..d10c888 100644 --- a/docs/index.rst +++ b/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 `_ transactional -email service into Django. +.. Eliminate the README's Travis build status indicator. + (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 -`django.core.mail `_ -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. +.. |buildstatus| replace:: \ -.. _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 = "" - EMAIL_BACKEND = "djrill.mail.backends.djrill.DjrillBackend" - - -3. Now the regular `Django email functions `_ - will send through Mandrill:: - - from django.core.mail import send_mail - - send_mail("It works!", "This will get sent through Mandrill", - "Djrill Sender ", ["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 ", - to=["Recipient One ", "another.person@example.com"], - headers={'Reply-To': "Service "} # optional extra headers - ) - msg.attach_alternative("

This is the HTML email body

", "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.) - +.. _toc: Documentation ------------- @@ -87,6 +24,7 @@ Documentation .. toctree:: :maxdepth: 2 + quickstart installation usage/sending_mail usage/templates diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..06be696 --- /dev/null +++ b/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 diff --git a/setup.py b/setup.py index bd08c5d..3e6fc3a 100644 --- a/setup.py +++ b/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() -with open('README.rst') as file: - long_description = file.read() + +def long_description_from_readme(rst): + # Patch up some rest substitution variables (references only - not definitions): + rst = re.sub(r'(?, Chris Jones ", author_email="kenneth@brack3t.com",