Update (almost) all the docs

docs/tips/django_templates.rst

@@ -0,0 +1,55 @@
+.. _django-templates:
+
+Using Django templates for email
+================================
+
+ESP's templating languages and merge capabilities are generally not compatible
+with each other, which can make it hard to move email templates between them.
+
+But since you're working in Django, you already have access to the
+extremely-full-featured :mod:`Django templating system <django.template>`.
+You don't even have to use Django's template syntax: it supports other
+template languages (like Jinja2).
+
+You're probably already using Django's templating system for your HTML pages,
+so it can be an easy decision to use it for your email, too.
+
+To compose email using *Django* templates, you can use Django's
+:func:`~django.template.loaders.django.template.loader.render_to_string`
+template shortcut to build the body and html.
+
+Example that builds an email from the templates ``message_subject.txt``,
+``message_body.txt`` and ``message_body.html``:
+
+.. code-block:: python
+
+    from django.core.mail import EmailMultiAlternatives
+    from django.template import Context
+    from django.template.loader import render_to_string
+
+    template_data = {
+        'ORDERNO': "12345", 'TRACKINGNO': "1Z987"
+    }
+
+    plaintext_context = Context(autoescape=False)  # HTML escaping not appropriate in plaintext
+    subject = render_to_string("message_subject.txt", template_data, plaintext_context)
+    text_body = render_to_string("message_body.txt", template_data, plaintext_context)
+    html_body = render_to_string("message_body.html", template_data)
+
+    msg = EmailMultiAlternatives(subject=subject, from_email="store@example.com",
+                                 to=["customer@example.com"], body=text_body)
+    msg.attach_alternative(html_body, "text/html")
+    msg.send()
+
+
+Helpful add-ons
+---------------
+
+These (third-party) packages can be helpful for building your email
+in Django:
+
+.. TODO: flesh this out
+
+* django-templated-mail
+* Premailer, for inlining css
+* BeautifulSoup, lxml, or html2text, for auto-generating plaintext from your html

docs/tips/index.rst

@@ -0,0 +1,16 @@
+Tips, tricks, and advanced usage
+--------------------------------
+
+Some suggestions and recipes for getting things
+done with Anymail:
+
+.. toctree::
+   :maxdepth: 1
+
+   multiple_backends
+   django_templates
+
+.. TODO:
+..    Working with django-mailer(2)
+..    Sharing backend connections (sessions)
+

docs/tips/multiple_backends.rst

@@ -0,0 +1,44 @@
+.. _multiple-backends:
+
+Mixing email backends
+=====================
+
+Since you are replacing Django's global :setting:`EMAIL_BACKEND`, by default
+Anymail will handle **all** outgoing mail, sending everything through your ESP.
+
+You can use Django mail's optional :func:`connection <django.core.mail.get_connection>`
+argument to send some mail through your ESP and others through a different system.
+
+This could be useful, for example, to deliver customer emails with the ESP,
+but send admin emails directly through an SMTP server:
+
+.. code-block:: python
+    :emphasize-lines: 8,10,13,15
+
+    from django.core.mail import send_mail, get_connection
+
+    # send_mail connection defaults to the settings EMAIL_BACKEND, which
+    # we've set to Anymail's MailgunBackend. This will be sent using Mailgun:
+    send_mail("Thanks", "We sent your order", "sales@example.com", ["customer@example.com"])
+
+    # Get a connection to an SMTP backend, and send using that instead:
+    smtp_backend = get_connection('django.core.mail.backends.smtp.EmailBackend')
+    send_mail("Uh-Oh", "Need your attention", "admin@example.com", ["alert@example.com"],
+              connection=smtp_backend)
+
+    # You can even use multiple Anymail backends in the same app:
+    sendgrid_backend = get_connection('anymail.backends.sendgrid.SendGridBackend')
+    send_mail("Password reset", "Here you go", "user@example.com", ["noreply@example.com"],
+              connection=sendgrid_backend)
+
+You can supply a different connection to Django's
+:func:`~django.core.mail.send_mail` and :func:`~django.core.mail.send_mass_mail` helpers,
+and in the constructor for an
+:class:`~django.core.mail.EmailMessage` or :class:`~django.core.mail.EmailMultiAlternatives`.
+
+
+(See the :class:`django.utils.log.AdminEmailHandler` docs for more information
+on Django's admin error logging.)
+
+.. _django.utils.log.AdminEmailHandler:
+    https://docs.djangoproject.com/en/stable/topics/logging/#django.utils.log.AdminEmailHandler