Clean up global MANDRILL_SETTINGS

* Clean up Djrill backend __init__
* Fold MANDRILL_SUBACCOUNT into
  global_settings logic
* Add some missing override tests
* Update docs

docs/history.rst

@@ -96,6 +96,9 @@ Other Djrill 2.0 Changes
   (You can also directly manage your own long-lived Djrill connection across multiple sends,
   by calling open and close on :ref:`Django's email backend <django:topic-email-backends>`.)
 
+* Add global :setting:`MANDRILL_SETTINGS` dict that can provide defaults
+  for most Djrill message options.
+
 * Add :exc:`djrill.NotSerializableForMandrillError`
 
 

docs/installation.rst

@@ -61,21 +61,42 @@ on invalid or rejected recipients. (Default ``False``.)
 .. versionadded:: 2.0
 
 
+.. setting:: MANDRILL_SETTINGS
+
+MANDRILL_SETTINGS
+~~~~~~~~~~~~~~~~~
+
+You can supply global default options to apply to all messages sent through Djrill.
+Set :setting:`!MANDRILL_SETTINGS` to a dict of these options. Example::
+
+    MANDRILL_SETTINGS = {
+        'subaccount': 'client-347',
+        'tracking_domain': 'example.com',
+        'track_opens': True,
+    }
+
+See :ref:`mandrill-send-support` for a list of available options. (Everything
+*except* :attr:`merge_vars`, :attr:`recipient_metadata`, and :attr:`send_at`
+can be used with :setting:`!MANDRILL_SETTINGS`.)
+
+Attributes set on individual EmailMessage objects will override the global
+:setting:`!MANDRILL_SETTINGS` for that message. :attr:`global_merge_vars`
+on an EmailMessage will be merged with any ``global_merge_vars`` in
+:setting:`!MANDRILL_SETTINGS` (with the ones on the EmailMessage taking
+precedence if there are conflicting var names).
+
+.. versionadded:: 2.0
+
+
 .. setting:: MANDRILL_SUBACCOUNT
 
 MANDRILL_SUBACCOUNT
 ~~~~~~~~~~~~~~~~~~~
 
-If you are using Mandrill's `subaccounts`_ feature, you can globally set the
-subaccount for all messages sent through Djrill::
-
-    MANDRILL_SUBACCOUNT = "client-347"
-
-(You can also set or override the :attr:`subaccount` on each individual message,
-with :ref:`Mandrill-specific sending options <mandrill-send-support>`.)
-
-.. versionadded:: 1.0
-   MANDRILL_SUBACCOUNT global setting
-
+Prior to Djrill 2.0, the :setting:`!MANDRILL_SUBACCOUNT` setting could
+be used to globally set the `Mandrill subaccount <subaccounts>`_.
+Although this is still supported for compatibility with existing code,
+new code should set a global subaccount in :setting:`MANDRILL_SETTINGS`
+as shown above.
 
 .. _subaccounts: http://help.mandrill.com/entries/25523278-What-are-subaccounts-

docs/usage/sending_mail.rst

@@ -103,24 +103,17 @@ Some notes and limitations:
 Mandrill-Specific Options
 -------------------------
 
-.. setting:: MANDRILL_SETTINGS
-
 Most of the options from the Mandrill
 `messages/send API <https://mandrillapp.com/api/docs/messages.html#method=send>`_
 `message` struct can be set directly on an :class:`~django.core.mail.EmailMessage`
-(or subclass) object:
-
-Most of these options can be globally set in your project's :file:`settings.py`
-using :setting:`MANDRILL_SETTINGS`. For Example::
-
-    MANDRILL_SETTINGS = {
-        'tracking_domain': 'example.com',
-        'track_opens': True,
-    }
+(or subclass) object.
 
 .. note::
-    ``merge_vars`` and ``recipient_metadata`` cannot be set globally. ``global_merge_vars`` is merged
-    (see :attribute:`global_merge_vars`)
+
+    You can set global defaults for common options with the
+    :setting:`MANDRILL_SETTINGS` setting, to avoid having to
+    set them on every message.
+
 
 .. These attributes are in the same order as they appear in the Mandrill API docs...
 
@@ -215,10 +208,6 @@ using :setting:`MANDRILL_SETTINGS`. For Example::
     Merge data must be strings or other JSON-serializable types.
     (See :ref:`formatting-merge-data` for details.)
 
-        .. note::
-
-        If using :setting:`MANDRILL_SETTINGS` then the message ``dict`` will be merged and overwrite any duplicates.
-
 .. attribute:: merge_vars
 
     ``dict``: per-recipient merge variables (most useful with :ref:`mandrill-templates`). The keys
@@ -244,8 +233,6 @@ using :setting:`MANDRILL_SETTINGS`. For Example::
 .. attribute:: subaccount
 
     ``str``: the ID of one of your subaccounts to use for sending this message.
-    (The subaccount on an individual message will override any global
-    :setting:`MANDRILL_SUBACCOUNT` setting.)
 
     .. versionadded:: 0.7