mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 03:41:05 -05:00
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
This commit is contained in:
medmunds
122
README.rst
122
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
|
||||
`django.core.mail <https://docs.djangoproject.com/en/dev/topics/email/>`_
|
||||
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 <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
|
||||
: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 = "<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.
|
||||
|
||||
@@ -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
|
||||
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 <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.
|
||||
.. |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 = "<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.)
|
||||
|
||||
.. _toc:
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
@@ -87,6 +24,7 @@ Documentation
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
installation
|
||||
usage/sending_mail
|
||||
usage/templates
|
||||
|
||||
9
docs/quickstart.rst
Normal file
9
docs/quickstart.rst
Normal file
@@ -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
|
||||
23
setup.py
23
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'(?<!\.\. )\|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",
|
||||
|
||||
Reference in New Issue
Block a user