docs: tweak email documentation - add gmail example

smtp_auth is too obscure to have in the .ini template.

development.ini

@@ -55,17 +55,16 b' pdebug = false'
 #error_email_from = [e-mail]
 
 ## SMTP server settings
-## Only smtp_server is mandatory. All other settings take the specified default
-## values.
+## If specifying credentials, make sure to use secure connections.
+## Default: Send unencrypted unauthenticated mails to the specified smtp_server.
+## For "SSL", use smtp_use_ssl = true and smtp_port = 465.
+## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).
-## If empty, use any of the authentication parameters supported by the server.
-#smtp_auth =
 
 [server:main]
 ## PASTE ##

docs/usage/email.rst

@@ -12,8 +12,17 b' cannot be sent, all mails will show up i'
 Before any email can be sent, an SMTP server has to be configured using the
 configuration file setting ``smtp_server``. If required for that server, specify
 a username (``smtp_username``) and password (``smtp_password``), a non-standard
-port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``)
-and/or specific authentication parameters (``smtp_auth``).
+port (``smtp_port``), whether to use "SSL" when connecting (``smtp_use_ssl``)
+or use STARTTLS (``smtp_use_tls``), and/or specify special ESMTP "auth" features
+(``smtp_auth``).
+
+For example, for sending through gmail, use::
+
+    smtp_server = smtp.gmail.com
+    smtp_username = username
+    smtp_password = password
+    smtp_port = 465
+    smtp_use_ssl = true
 
 
 Application emails

kallithea/bin/template.ini.mako

@@ -49,17 +49,16 b' pdebug = false'
 #error_email_from = [e-mail]
 
 <%text>## SMTP server settings</%text>
-<%text>## Only smtp_server is mandatory. All other settings take the specified default</%text>
-<%text>## values.</%text>
+<%text>## If specifying credentials, make sure to use secure connections.</%text>
+<%text>## Default: Send unencrypted unauthenticated mails to the specified smtp_server.</%text>
+<%text>## For "SSL", use smtp_use_ssl = true and smtp_port = 465.</%text>
+<%text>## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.</%text>
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-<%text>## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).</%text>
-<%text>## If empty, use any of the authentication parameters supported by the server.</%text>
-#smtp_auth =
 
 [server:main]
 %if http_server == 'paste':

kallithea/config/deployment.ini_tmpl

@@ -50,17 +50,16 b' pdebug = false'
 #error_email_from = [e-mail]
 
 ## SMTP server settings
-## Only smtp_server is mandatory. All other settings take the specified default
-## values.
+## If specifying credentials, make sure to use secure connections.
+## Default: Send unencrypted unauthenticated mails to the specified smtp_server.
+## For "SSL", use smtp_use_ssl = true and smtp_port = 465.
+## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).
-## If empty, use any of the authentication parameters supported by the server.
-#smtp_auth =
 
 [server:main]
 ## PASTE ##

kallithea/tests/test.ini

@@ -53,17 +53,16 b' pdebug = false'
 #error_email_from = [e-mail]
 
 ## SMTP server settings
-## Only smtp_server is mandatory. All other settings take the specified default
-## values.
+## If specifying credentials, make sure to use secure connections.
+## Default: Send unencrypted unauthenticated mails to the specified smtp_server.
+## For "SSL", use smtp_use_ssl = true and smtp_port = 465.
+## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.
 #smtp_server = smtp.example.com
 #smtp_username =
 #smtp_password =
 #smtp_port = 25
+#smtp_use_ssl = false
 #smtp_use_tls = false
-#smtp_use_ssl = false
-## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).
-## If empty, use any of the authentication parameters supported by the server.
-#smtp_auth =
 
 [server:main]
 ## PASTE ##