Docs: add notes to esp-feature-matrix

Use footnotes to clarify some details
in the supported features table.

Closes #377

Author: medmunds

docs/_static/anymail-theme.css

@@ -17,6 +17,19 @@ table.sticky-left th:first-of-type[colspan] > p {
   left: 17px; /* (.wy-table $table-padding-size) + (docutils border="1" in html) */
 }
 
+/* Fix footnote stacking in sticky table */
+.rst-content .citation-reference,
+.rst-content .footnote-reference {
+  /* Original (but `position: relative` creates a new stacking context):
+  vertical-align: baseline;
+  position: relative;
+  top: -.4em;
+  */
+  vertical-align: 0.4em;
+  position: static;
+  top: initial; /* (not relevant with `position: static`) */
+}
+
 /* Show code cross-reference links as clickable $link-color (blue).
 
    Sphinx-rtd-theme usually wants `.rst-content a code` to be $link-color [1], but has

docs/docutils.conf

@@ -0,0 +1,6 @@
+[general]
+footnote_backlinks: false
+trim_footnote_reference_space: true
+
+[html writers]
+footnote_references: superscript

docs/esps/esp-feature-matrix.csv

@@ -1,18 +1,18 @@
 Email Service Provider,:ref:`amazon-ses-backend`,:ref:`brevo-backend`,:ref:`mailersend-backend`,:ref:`mailgun-backend`,:ref:`mailjet-backend`,:ref:`mandrill-backend`,:ref:`postal-backend`,:ref:`postmark-backend`,:ref:`resend-backend`,:ref:`sendgrid-backend`,:ref:`sparkpost-backend`,:ref:`unisender-go-backend`
 .. rubric:: :ref:`Anymail send options <anymail-send-options>`,,,,,,,,,,,,
 :attr:`~AnymailMessage.envelope_sender`,Yes,No,No,Domain only,Yes,Domain only,Yes,No,No,No,Yes,No
-:attr:`~AnymailMessage.merge_headers`,Yes*,Yes,No,Yes,Yes,No,No,Yes,Yes,Yes,Yes*,Yes*
+:attr:`~AnymailMessage.merge_headers`,Yes [#caveats]_,Yes,No,Yes,Yes,No,No,Yes,Yes,Yes,Yes [#caveats]_,Yes [#caveats]_
 :attr:`~AnymailMessage.metadata`,Yes,Yes,No,Yes,Yes,Yes,No,Yes,Yes,Yes,Yes,Yes
-:attr:`~AnymailMessage.merge_metadata`,Yes*,Yes,No,Yes,Yes,Yes,No,Yes,Yes,Yes,Yes,Yes
+:attr:`~AnymailMessage.merge_metadata`,Yes [#caveats]_,Yes,No,Yes,Yes,Yes,No,Yes,Yes,Yes,Yes,Yes
 :attr:`~AnymailMessage.send_at`,No,Yes,Yes,Yes,No,Yes,No,No,No,Yes,Yes,Yes
 :attr:`~AnymailMessage.tags`,Yes,Yes,Yes,Yes,Max 1 tag,Yes,Max 1 tag,Max 1 tag,Yes,Yes,Max 1 tag,Yes
-:attr:`~AnymailMessage.track_clicks`,No,No,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:attr:`~AnymailMessage.track_opens`,No,No,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.track_clicks`,No [#nocontrol]_,No [#nocontrol]_,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.track_opens`,No [#nocontrol]_,No [#nocontrol]_,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
 :ref:`amp-email`,Yes,No,No,Yes,No,No,No,No,No,Yes,Yes,Yes
 .. rubric:: :ref:`templates-and-merge`,,,,,,,,,,,,
 :attr:`~AnymailMessage.template_id`,Yes,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:attr:`~AnymailMessage.merge_data`,Yes*,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
-:attr:`~AnymailMessage.merge_global_data`,Yes*,Yes,(emulated),(emulated),Yes,Yes,No,Yes,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.merge_data`,Yes [#caveats]_,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
+:attr:`~AnymailMessage.merge_global_data`,Yes [#caveats]_,Yes,Yes,Yes,Yes,Yes,No,Yes,No,Yes,Yes,Yes
 .. rubric:: :ref:`Status <esp-send-status>` and :ref:`event tracking <event-tracking>`,,,,,,,,,,,,
 :attr:`~AnymailMessage.anymail_status`,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes
 :class:`~anymail.signals.AnymailTrackingEvent` from webhooks,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes,Yes

docs/esps/index.rst

@@ -48,7 +48,13 @@ The table below summarizes the Anymail features supported for each ESP.
     :widths: auto
     :class: sticky-left
 
-\* See ESP detail page for limitations and clarifications
+.. [#caveats]
+    Some restrictions apply---see the ESP detail page
+    (usually under "Limitations and Quirks").
+
+.. [#nocontrol]
+    The ESP supports tracking, but Anymail can't enable/disable it
+    for individual messages. See the ESP detail page for more information.
 
 Trying to choose an ESP? Please **don't** start with this table. It's far more
 important to consider things like an ESP's deliverability stats, latency, uptime,