Merge "Docs: reformat sql driver docs" into feature/zuulv3
diff --git a/doc/source/admin/drivers/sql.rst b/doc/source/admin/drivers/sql.rst
index 17bfa8d..4c4a729 100644
--- a/doc/source/admin/drivers/sql.rst
+++ b/doc/source/admin/drivers/sql.rst
@@ -4,14 +4,29 @@
===
The SQL driver supports reporters only. Only one connection per
-database is permitted. The connection options are:
+database is permitted.
-**driver=sql**
+Connection Configuration
+------------------------
-**dburi**
- Database connection information in the form of a URI understood by
- sqlalchemy. eg http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls
- ``dburi=mysql://user:pass@localhost/db``
+The connection options for the SQL driver are:
+
+.. attr:: <sql connection>
+
+ .. attr:: driver
+ :required:
+
+ .. value:: sql
+
+ The connection must set ``driver=sql`` for SQL connections.
+
+ .. attr:: dburi
+ :required:
+
+ Database connection information in the form of a URI understood
+ by SQLAlchemy. See `The SQLAlchemy manual
+ <http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls>`_
+ for more information.
Reporter Configuration
----------------------
@@ -21,9 +36,26 @@
A :ref:`connection<connections>` that uses the sql driver must be
supplied to the reporter.
-zuul.conf contains the database connection and credentials. To store different
-reports in different databases you'll need to create a new connection per
-database.
+``zuul.conf`` contains the database connection and credentials. To
+store different reports in different databases you'll need to create a
+new connection per database.
-The SQL reporter does nothing on "start" or "merge-failure"; it only
-acts on "success" or "failure" reporting stages.
+The SQL reporter does nothing on :attr:`pipeline.start` or
+:attr:`pipeline.merge-failure`; it only acts on
+:attr:`pipeline.success` or :attr:`pipeline.failure` reporting stages.
+
+For example:
+
+.. code-block:: yaml
+
+ - pipeline:
+ name: post-merge
+ success:
+ mydb_conn: {}
+ failure:
+ mydb_conn: {}
+
+.. attr:: pipeline.<reporter>.<sql source>
+
+ To report to a database, add an empty dictionary to the desired
+ pipeline :ref:`reporter<reporters>` attributes.