Clean up the SMTP returner docstring and show an actual config example

This is a frequent stumbling block for users unaccustomed to the older
`mod.setting` configuration syntax. Often they will interpret the list
of settings as needing to be underneat a top-level `smtp` dictionary.

This has been on my todo list for a looong time. :-P

salt/returners/smtp_return.py

@@ -2,58 +2,47 @@
 '''
 Return salt data via email
 
-The following fields can be set in the minion conf file::
+The following fields can be set in the minion conf file. Fields are optional
+unless noted otherwise.
 
-    smtp.from (required)
-    smtp.to (required)
-    smtp.host (required)
-    smtp.port (optional, defaults to 25)
-    smtp.username (optional)
-    smtp.password (optional)
-    smtp.tls (optional, defaults to False)
-    smtp.subject (optional, but helpful)
-    smtp.gpgowner (optional)
-    smtp.fields (optional)
-    smtp.template (optional)
-    smtp.renderer (optional)
+* ``from`` (required) The name/address of the email sender.
+* ``to`` (required) The name/address of the email recipient.
+* ``host`` (required) The SMTP server hostname or address.
+* ``port`` The SMTP server port; defaults to ``25``.
+* ``username`` The username used to authenticate to the server. If specified a
+    password is also required. It is recommended but not required to also use
+    TLS with this option.
+* ``password`` The password used to authenticate to the server.
+* ``tls`` Whether to secure the connection using TLS; defaults to ``False``
+* ``subject`` The email subject line.
+* ``fields`` Which fields from the returned data to include in the subject line
+    of the email; comma-delimited. For example: ``id,fun``. Please note, *the
+    subject line is not encrypted*.
+* ``gpgowner`` A user's :file:`~/.gpg` directory. This must contain a gpg
+    public key matching the address the mail is sent to. If left unset, no
+    encryption will be used. Requires :program:`python-gnupg` to be installed.
+* ``template`` The path to a file to be used as a template for the email body.
+* ``renderer`` A Salt renderer, or render-pipe, to use to render the email
+    template. Default ``jinja``.
+
+Below is an example of the above settings in a Salt Minion configuration file:
+
+.. code-block:: yaml
+
+    smtp.from: me@example.net
+    smtp.to: you@example.com
+    smtp.host: localhost
+    smtp.port: 1025
 
 Alternative configuration values can be used by prefacing the configuration.
 Any values not found in the alternative configuration will be pulled from
-the default location::
+the default location. For example:
 
-    alternative.smtp.from
-    alternative.smtp.to
-    alternative.smtp.host
-    alternative.smtp.port
-    alternative.smtp.username
-    alternative.smtp.password
-    alternative.smtp.tls
-    alternative.smtp.subject
-    alternative.smtp.gpgowner
-    alternative.smtp.fields
-    alternative.smtp.template
-    alternative.smtp.renderer
+.. code-block:: yaml
 
-There are a few things to keep in mind:
-
-* If a username is used, a password is also required. It is recommended (but
-  not required) to use the TLS setting when authenticating.
-* You should at least declare a subject, but you don't have to.
-* The use of encryption, i.e. setting gpgowner in your settings, requires
-  python-gnupg to be installed.
-* The field gpgowner specifies a user's ~/.gpg directory. This must contain a
-  gpg public key matching the address the mail is sent to. If left unset, no
-  encryption will be used.
-* smtp.fields lets you include the value(s) of various fields in the subject
-  line of the email. These are comma-delimited. For instance::
-
-    smtp.fields: id,fun
-
-  ...will display the id of the minion and the name of the function in the
-  subject line. You may also use 'jid' (the job id), but it is generally
-  recommended not to use 'return', which contains the entire return data
-  structure (which can be very large). Also note that the subject is always
-  unencrypted.
+    alternative.smtp.username: saltdev
+    alternative.smtp.password: saltdev
+    alternative.smtp.tls: True
 
 To use the SMTP returner, append '--return smtp' to the salt command.
 
@@ -69,6 +58,13 @@ To use the alternative configuration, append '--return_config alternative' to th
 
     salt '*' test.ping --return smtp --return_config alternative
 
+An easy way to test the SMTP returner is to use the development SMTP server
+built into Python. The command below will start a single-threaded SMTP server
+that prints any email it receives to the console.
+
+.. code-block:: python
+
+    python -m smtpd -n -c DebuggingServer localhost:1025
 '''
 from __future__ import absolute_import