Merge "Docs: reformat SMTP driver docs" into feature/zuulv3

doc/source/admin/drivers/smtp.rst

@@ -9,25 +9,36 @@ when items report.
 Connection Configuration
 ------------------------
 
-**driver=smtp**
+.. attr:: <smtp connection>
+
+   .. attr:: driver
+      :required:
+
+      .. value:: smtp
+
+         The connection must set ``driver=smtp`` for SMTP connections.
+
+   .. attr:: server
+      :default: localhost
 
-**server**
       SMTP server hostname or address to use.
-  ``server=localhost``
 
-**port**
+   .. attr:: port
-  Optional: SMTP server port.
+      :default: 25
-  ``port=25``
+
+      SMTP server port.
+
+   .. attr:: default_from
+      :default: zuul
 
-**default_from**
       Who the email should appear to be sent from when emailing the report.
       This can be overridden by individual pipelines.
-  ``default_from=zuul@example.com``
 
-**default_to**
+   .. attr:: default_to
+      :default: zuul
+
       Who the report should be emailed to by default.
       This can be overridden by individual pipelines.
-  ``default_to=you@example.com``
 
 Reporter Configuration
 ----------------------
@@ -39,7 +50,9 @@ reporter.  The connection also may specify a default *To* or *From*
 address.
 
 Each pipeline can overwrite the ``subject`` or the ``to`` or ``from`` address by
-providing alternatives as arguments to the reporter. For example, ::
+providing alternatives as arguments to the reporter. For example:
+
+.. code-block:: yaml
 
    - pipeline:
        name: post-merge
@@ -51,3 +64,24 @@ providing alternatives as arguments to the reporter. For example, ::
            to: you@example.com
            from: alternative@example.com
            subject: Change {change} failed
+
+.. attr:: pipeline.<reporter>.<smtp source>
+
+   To report via email, the dictionaries passed to any of the pipeline
+   :ref:`reporter<reporters>` attributes support the following
+   attributes:
+
+   .. attr:: to
+
+      The SMTP recipient address for the report.  Multiple addresses
+      may be specified as one value separated by commas.
+
+   .. attr:: from
+
+      The SMTP sender address for the report.
+
+   .. attr:: subject
+
+      The Subject of the report email.
+
+      .. TODO: document subject string formatting.

zuul/driver/smtp/smtpreporter.py

@@ -47,7 +47,6 @@ class SMTPReporter(BaseReporter):
 
 def getSchema():
     smtp_reporter = v.Schema({
-        'connection': str,
         'to': str,
         'from': str,
         'subject': str,