Docs: reformat gerrit driver docs
Change-Id: I29479dba0f0dde936a72c07e23207570e7c89fd5
diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
index 454f8d0..8467ed8 100644
--- a/doc/source/admin/drivers/gerrit.rst
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -24,44 +24,57 @@
Connection Configuration
------------------------
-The supported options in zuul.conf connections are:
+The supported options in ``zuul.conf`` connections are:
-**driver=gerrit**
+.. attr:: <gerrit connection>
-**server**
- FQDN of Gerrit server.
- ``server=review.example.com``
+ .. attr:: driver
+ :required:
-**canonical_hostname**
- The canonical hostname associated with the git repos on the Gerrit
- server. Defaults to the value of **server**. This is used to
- identify projects from this connection by name and in preparing
- repos on the filesystem for use by jobs. Note that Zuul will still
- only communicate with the Gerrit server identified by **server**;
- this option is useful if users customarily use a different hostname
- to clone or pull git repos so that when Zuul places them in the
- job's working directory, they appear under this directory name.
- ``canonical_hostname=git.example.com``
+ .. value:: gerrit
-**port**
- Optional: Gerrit server port.
- ``port=29418``
+ The connection must set ``driver=gerrit`` for Gerrit connections.
-**baseurl**
- Optional: path to Gerrit web interface. Defaults to ``https://<value
- of server>/``. ``baseurl=https://review.example.com/review_site/``
+ .. attr:: server
-**user**
- User name to use when logging into above server via ssh.
- ``user=zuul``
+ Fully qualified domain name of Gerrit server.
-**sshkey**
- Path to SSH key to use when logging into above server.
- ``sshkey=/home/zuul/.ssh/id_rsa``
+ .. attr:: canonical_hostname
-**keepalive**
- Optional: Keepalive timeout, 0 means no keepalive.
- ``keepalive=60``
+ The canonical hostname associated with the git repos on the
+ Gerrit server. Defaults to the value of
+ :attr:`<gerrit connection>.server`. This is used to identify
+ projects from this connection by name and in preparing repos on
+ the filesystem for use by jobs. Note that Zuul will still only
+ communicate with the Gerrit server identified by ``server``;
+ this option is useful if users customarily use a different
+ hostname to clone or pull git repos so that when Zuul places
+ them in the job's working directory, they appear under this
+ directory name.
+
+ .. attr:: port
+ :default: 29418
+
+ Gerrit server port.
+
+ .. attr:: baseurl
+
+ Path to Gerrit web interface.
+
+ .. attr:: user
+ :default: zuul
+
+ User name to use when logging into Gerrit via ssh.
+
+ .. attr:: sshkey
+ :default: ~zuul/.ssh/id_rsa
+
+ Path to SSH key to use when logging into Gerrit.
+
+ .. attr:: keepalive
+ :default: 60
+
+ SSH connection keepalive timeout; ``0`` disables.
Trigger Configuration
---------------------
@@ -74,85 +87,88 @@
that is granted the ``Stream Events`` permission, otherwise it will not
be able to invoke the ``gerrit stream-events`` command over SSH.
-The supported pipeline trigger options are:
+.. attr:: pipeline.trigger.<gerrit source>
-**event**
- The event name from gerrit. Examples: ``patchset-created``,
- ``comment-added``, ``ref-updated``. This field is treated as a
- regular expression.
+ The dictionary passed to the Gerrit pipeline `trigger` attribute
+ supports the following attributes:
-**branch**
- The branch associated with the event. Example: ``master``. This
- field is treated as a regular expression, and multiple branches may
- be listed.
+ .. attr:: event
+ :required:
-**ref**
- On ref-updated events, the branch parameter is not used, instead the
- ref is provided. Currently Gerrit has the somewhat idiosyncratic
- behavior of specifying bare refs for branch names (e.g.,
- ``master``), but full ref names for other kinds of refs (e.g.,
- ``refs/tags/foo``). Zuul matches what you put here exactly against
- what Gerrit provides. This field is treated as a regular
- expression, and multiple refs may be listed.
+ The event name from gerrit. Examples: ``patchset-created``,
+ ``comment-added``, ``ref-updated``. This field is treated as a
+ regular expression.
-**ignore-deletes**
- When a branch is deleted, a ref-updated event is emitted with a
- newrev of all zeros specified. The ``ignore-deletes`` field is a
- boolean value that describes whether or not these newrevs trigger
- ref-updated events. The default is True, which will not trigger
- ref-updated events.
+ .. attr:: branch
-**approval**
- This is only used for ``comment-added`` events. It only matches if
- the event has a matching approval associated with it. Example:
- ``Code-Review: 2`` matches a ``+2`` vote on the code review
- category. Multiple approvals may be listed.
+ The branch associated with the event. Example: ``master``.
+ This field is treated as a regular expression, and multiple
+ branches may be listed.
-**email**
- This is used for any event. It takes a regex applied on the
- performer email, i.e. Gerrit account email address. If you want to
- specify several email filters, you must use a YAML list. Make sure
- to use non greedy matchers and to escapes dots! Example: ``email:
- ^.*?@example\.org$``.
+ .. attr:: ref
-**email_filter** (deprecated)
- A deprecated alternate spelling of *email*. Only one of *email* or
- *email_filter* should be used.
+ On ref-updated events, the branch parameter is not used, instead
+ the ref is provided. Currently Gerrit has the somewhat
+ idiosyncratic behavior of specifying bare refs for branch names
+ (e.g., ``master``), but full ref names for other kinds of refs
+ (e.g., ``refs/tags/foo``). Zuul matches this value exactly
+ against what Gerrit provides. This field is treated as a
+ regular expression, and multiple refs may be listed.
-**username**
- This is used for any event. It takes a regex applied on the
- performer username, i.e. Gerrit account name. If you want to
- specify several username filters, you must use a YAML list. Make
- sure to use non greedy matchers and to escapes dots! Example:
- ``username: ^jenkins$``.
+ .. attr:: ignore-deletes
+ :default: true
-**username_filter** (deprecated)
- A deprecated alternate spelling of *username*. Only one of
- *username* or *username_filter* should be used.
+ When a branch is deleted, a ref-updated event is emitted with a
+ newrev of all zeros specified. The ``ignore-deletes`` field is a
+ boolean value that describes whether or not these newrevs
+ trigger ref-updated events.
-**comment**
- This is only used for ``comment-added`` events. It accepts a list
- of regexes that are searched for in the comment string. If any of
- these regexes matches a portion of the comment string the trigger is
- matched. ``comment: retrigger`` will match when comments containing
- 'retrigger' somewhere in the comment text are added to a change.
+ .. attr:: approval
-**comment_filter** (deprecated)
- A deprecated alternate spelling of *comment*. Only one of *comment*
- or *comment_filter* should be used.
+ This is only used for ``comment-added`` events. It only matches
+ if the event has a matching approval associated with it.
+ Example: ``Code-Review: 2`` matches a ``+2`` vote on the code
+ review category. Multiple approvals may be listed.
-**require-approval**
- This may be used for any event. It requires that a certain kind of
- approval be present for the current patchset of the change (the
- approval could be added by the event in question). It follows the
- same syntax as :attr:`pipeline.require.<gerrit
- source>.approval`. For each specified criteria there must exist a
- matching approval.
+ .. attr:: email
-**reject-approval**
- This takes a list of approvals in the same format as
- *require-approval* but will fail to enter the pipeline if there is a
- matching approval.
+ This is used for any event. It takes a regex applied on the
+ performer email, i.e. Gerrit account email address. If you want
+ to specify several email filters, you must use a YAML list.
+ Make sure to use non greedy matchers and to escapes dots!
+ Example: ``email: ^.*?@example\.org$``.
+
+ .. attr:: username
+
+ This is used for any event. It takes a regex applied on the
+ performer username, i.e. Gerrit account name. If you want to
+ specify several username filters, you must use a YAML list.
+ Make sure to use non greedy matchers and to escapes dots.
+ Example: ``username: ^zuul$``.
+
+ .. attr:: comment
+
+ This is only used for ``comment-added`` events. It accepts a
+ list of regexes that are searched for in the comment string. If
+ any of these regexes matches a portion of the comment string the
+ trigger is matched. ``comment: retrigger`` will match when
+ comments containing ``retrigger`` somewhere in the comment text
+ are added to a change.
+
+ .. attr:: require-approval
+
+ This may be used for any event. It requires that a certain kind
+ of approval be present for the current patchset of the change
+ (the approval could be added by the event in question). It
+ follows the same syntax as :attr:`pipeline.require.<gerrit
+ source>.approval`. For each specified criteria there must exist
+ a matching approval.
+
+ .. attr:: reject-approval
+
+ This takes a list of approvals in the same format as
+ :attr:`pipeline.trigger.<gerrit source>.require-approval` but
+ will fail to enter the pipeline if there is a matching approval.
Reporter Configuration
----------------------
@@ -178,18 +194,20 @@
pipelines may specify that items meet certain conditions in order to
be enqueued into the pipeline. These conditions vary according to the
source of the project in question. To supply requirements for changes
-from a Gerrit source named *my-gerrit*, create a configuration such as
-the following::
+from a Gerrit source named ``my-gerrit``, create a configuration such
+as the following:
- pipeline:
- require:
- my-gerrit:
- approval:
- - Code-Review: 2
+.. code-block:: yaml
+
+ pipeline:
+ require:
+ my-gerrit:
+ approval:
+ - Code-Review: 2
This indicates that changes originating from the Gerrit connection
-named *my-gerrit* must have a Code Review vote of +2 in order to be
-enqueued into the pipeline.
+named ``my-gerrit`` must have a ``Code-Review`` vote of ``+2`` in
+order to be enqueued into the pipeline.
.. attr:: pipeline.require.<gerrit source>
@@ -260,9 +278,11 @@
pipeline. It follows the same syntax as
:attr:`pipeline.require.<gerrit source>.approval`.
- Example to reject a change with any negative vote::
+ Example to reject a change with any negative vote:
- reject:
- my-gerrit:
- approval:
- - Code-Review: [-1, -2]
+ .. code-block:: yaml
+
+ reject:
+ my-gerrit:
+ approval:
+ - Code-Review: [-1, -2]