integration docs: Document new email integration behaviors.

Tweaked by tabbott for cleaner, more precise English.

templates/zerver/integrations/email.md

@@ -21,3 +21,22 @@ To send an email to a Zulip stream:
 
 Please note that it may take up to one minute for the message to show
 up in Zulip.
+
+**Additional options**
+
+The default behavior of this integration is designed to be convenient
+in the common case.  We offer a few options for overriding the default
+behavior, configured by editing the Zulip email address:
+
+Example: `{{ email_gateway_example_with_options }}`
+
+* `show-sender`: Will cause `From: <Sender email address>` to be
+  displayed at the top of Zulip messages sent via this integration.
+* `include-footer`: Include footer sections of emails (by default,
+  they are not included, to minimize clutter).
+* `include-quotes`: Include quoted sections of emails in the Zulip
+  message (By default, Zulip includes them only for forwarded emails,
+  i.e. those where the subject starts with `Fwd:` or similar)
+* You can use `+` instead of the `.` separators if you prefer.  We
+  recommend the `.` syntax by default because Google Groups silently
+  drops `+` from email addresses subscribed to its mailing lists.

zerver/tests/test_docs.py

@@ -208,11 +208,11 @@ class DocPageTest(ZulipTestCase):
 
     def test_email_integration(self) -> None:
         self._test('/integrations/doc-html/email',
-                   'support+abcdefg@testserver', doc_html_str=True)
+                   'support.abcd1234@testserver', doc_html_str=True)
 
         with self.settings(EMAIL_GATEWAY_PATTERN=''):
             result = self.get_doc('integrations/doc-html/email', subdomain='zulip')
-            self.assertNotIn('support+abcdefg@testserver', str(result.content))
+            self.assertNotIn('support.abcd1234@testserver', str(result.content))
             # if EMAIL_GATEWAY_PATTERN is empty, the main /integrations page should
             # be rendered instead
             self._test('/integrations/', 'native integrations.')

zerver/views/documentation.py

@@ -195,6 +195,7 @@ def integration_doc(request: HttpRequest, integration_name: str=REQ(default=None
         context['hubot_docs_url'] = integration.hubot_docs_url
     if isinstance(integration, EmailIntegration):
         context['email_gateway_example'] = settings.EMAIL_GATEWAY_EXAMPLE
+        context['email_gateway_example_with_options'] = settings.EMAIL_GATEWAY_EXAMPLE_WITH_OPTIONS
 
     doc_html_str = render_markdown_path(integration.doc, context)
 

zproject/settings.py

@@ -829,9 +829,12 @@ for bot in INTERNAL_BOTS + REALM_INTERNAL_BOTS + DISABLED_REALM_INTERNAL_BOTS:
         vars()[bot['var_name']] = bot_email
 
 if EMAIL_GATEWAY_PATTERN != "":
-    EMAIL_GATEWAY_EXAMPLE = EMAIL_GATEWAY_PATTERN % ("support+abcdefg",)
+    EMAIL_GATEWAY_EXAMPLE = EMAIL_GATEWAY_PATTERN % ("support.abcd1234",)
+    EMAIL_GATEWAY_EXAMPLE_WITH_OPTIONS = EMAIL_GATEWAY_PATTERN % (
+        "support.abcd1234.first-option.second-option",)
 else:
     EMAIL_GATEWAY_EXAMPLE = ""
+    EMAIL_GATEWAY_EXAMPLE_WITH_OPTIONS = ""
 
 ########################################################################
 # STATSD CONFIGURATION