diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
index 8467ed8..ac42bd3 100644
--- a/doc/source/admin/drivers/gerrit.rst
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -89,7 +89,7 @@
 
 .. attr:: pipeline.trigger.<gerrit source>
 
-   The dictionary passed to the Gerrit pipeline `trigger` attribute
+   The dictionary passed to the Gerrit pipeline ``trigger`` attribute
    supports the following attributes:
 
    .. attr:: event
diff --git a/doc/source/admin/drivers/github.rst b/doc/source/admin/drivers/github.rst
index cbbc5cc..7eebbdc 100644
--- a/doc/source/admin/drivers/github.rst
+++ b/doc/source/admin/drivers/github.rst
@@ -29,135 +29,189 @@
 ``app_key`` are required. If the Webhook approach is taken, the ``api_token``
 setting is required.
 
-The supported options in zuul.conf connections are:
+The supported options in ``zuul.conf`` connections are:
 
-**driver=github**
+.. attr:: <github connection>
 
-**app_id**
-  App ID if you are using a GitHub App. Can be found under the "Public Link"
-  on the right hand side labeled "ID".
-  ``app_id=1234``
+   .. attr:: driver
+      :required:
 
-**app_key**
-  Path to a file containing the Secret Key Zuul will use to create tokens for
-  the API interactions. In Github this is known as "Private key" and must be
-  collected when generated.
-  ``app_key=/etc/zuul/github.key``
+      .. value:: github
 
-**api_token**
-  API token for accessing GitHub if Zuul is configured with Webhooks.
-  See `Creating an access token for command-line use
-  <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
+         The connection must set ``driver=github`` for GitHub connections.
 
-**webhook_token**
-  Required token for validating the webhook event payloads.  In the
-  GitHub App Configuration page, this is called "Webhook secret".
-  See `Securing your webhooks
-  <https://developer.github.com/webhooks/securing/>`_.
+   .. attr:: app_id
 
-**sshkey**
-  Path to SSH key to use when cloning github repositories.
-  ``sshkey=/home/zuul/.ssh/id_rsa``
+      App ID if you are using a *GitHub App*. Can be found under the
+      **Public Link** on the right hand side labeled **ID**.
 
-**server**
-  Optional: Hostname of the github install (such as a GitHub Enterprise)
-  If not specified, defaults to ``github.com``
-  ``server=github.myenterprise.com``
+   .. attr:: app_key
 
-**canonical_hostname**
-  The canonical hostname associated with the git repos on the GitHub
-  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 GitHub 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``
+      Path to a file containing the secret key Zuul will use to create
+      tokens for the API interactions. In Github this is known as
+      **Private key** and must be collected when generated.
 
-**verify_ssl**
-  Optional: Enable or disable ssl verification for GitHub Enterprise.  This is
-  useful for a connection to a test installation. If not specified, defaults
-  to ``true``.
-  ``verify_ssl=true``
+   .. attr:: api_token
+
+      API token for accessing GitHub if Zuul is configured with
+      Webhooks.  See `Creating an access token for command-line use
+      <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
+
+   .. attr:: webhook_token
+
+      Required token for validating the webhook event payloads.  In
+      the GitHub App Configuration page, this is called **Webhook
+      secret**.  See `Securing your webhooks
+      <https://developer.github.com/webhooks/securing/>`_.
+
+   .. attr:: sshkey
+      :default: ~/.ssh/id_rsa
+
+      Path to SSH key to use when cloning github repositories.
+
+   .. attr:: server
+      :default: github.com
+
+      Hostname of the github install (such as a GitHub Enterprise).
+
+   .. attr:: canonical_hostname
+
+      The canonical hostname associated with the git repos on the
+      GitHub server.  Defaults to the value of :attr:`<github
+      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 GitHub 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:: verify_ssl
+      :default: true
+
+      Enable or disable ssl verification for GitHub Enterprise.  This
+      is useful for a connection to a test installation.
 
 Trigger Configuration
 ---------------------
 GitHub webhook events can be configured as triggers.
 
-A connection name with the github driver can take multiple events with the
-following options.
+A connection name with the GitHub driver can take multiple events with
+the following options.
 
-**event**
-  The event from github. Supported events are ``pull_request``,
-  ``pull_request_review``, and ``push``.
+.. attr:: pipeline.trigger.<github source>
 
-  A ``pull_request`` event will have associated action(s) to trigger
-  from. The supported actions are:
+   The dictionary passed to the GitHub pipeline ``trigger`` attribute
+   supports the following attributes:
 
-    *opened* - pull request opened
+   .. attr:: event
+      :required:
 
-    *changed* - pull request synchronized
+      The event from github. Supported events are:
 
-    *closed* - pull request closed
+      .. value:: pull_request
 
-    *reopened* - pull request reopened
+      .. value:: pull_request_review
 
-    *comment* - comment added on pull request
+      .. value:: push
 
-    *labeled* - label added on pull request
+   .. attr:: action
 
-    *unlabeled* - label removed from pull request
+      A :value:`pipeline.trigger.<github source>.event.pull_request`
+      event will have associated action(s) to trigger from. The
+      supported actions are:
 
-    *status* - status set on commit
+      .. value:: opened
 
-  A ``pull_request_review`` event will
-  have associated action(s) to trigger from. The supported actions are:
+         Pull request opened.
 
-    *submitted* - pull request review added
+      .. value:: changed
 
-    *dismissed* - pull request review removed
+         Pull request synchronized.
 
-**branch**
-  The branch associated with the event. Example: ``master``.  This
-  field is treated as a regular expression, and multiple branches may
-  be listed. Used for ``pull_request`` and ``pull_request_review``
-  events.
+      .. value:: closed
 
-**comment**
-  This is only used for ``pull_request`` ``comment`` actions.  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 pull request.
+         Pull request closed.
 
-**label**
-  This is only used for ``labeled`` and ``unlabeled`` ``pull_request``
-  actions.  It accepts a list of strings each of which matches the
-  label name in the event literally.  ``label: recheck`` will match a
-  ``labeled`` action when pull request is labeled with a ``recheck``
-  label. ``label: 'do not test'`` will match a ``unlabeled`` action
-  when a label with name ``do not test`` is removed from the pull
-  request.
+      .. value:: reopened
 
-**state**
-  This is only used for ``pull_request_review`` events.  It accepts a
-  list of strings each of which is matched to the review state, which
-  can be one of ``approved``, ``comment``, or ``request_changes``.
+         Pull request reopened.
 
-**status**
-  This is used for ``pull-request`` and ``status`` actions. It accepts
-  a list of strings each of which matches the user setting the status,
-  the status context, and the status itself in the format of
-  ``user:context:status``.  For example,
-  ``zuul_github_ci_bot:check_pipeline:success``.
+      .. value:: comment
 
-**ref**
-  This is only used for ``push`` events. This field is treated as a
-  regular expression and multiple refs may be listed. GitHub always
-  sends full ref name, eg. ``refs/tags/bar`` and this string is
-  matched against the regexp.
+         Comment added to pull request.
+
+      .. value:: labeled
+
+         Label added to pull request.
+
+      .. value:: unlabeled
+
+         Label removed from pull request.
+
+      .. value:: status
+
+         Status set on commit.
+
+      A :value:`pipeline.trigger.<github
+      source>.event.pull_request_review` event will have associated
+      action(s) to trigger from. The supported actions are:
+
+      .. value:: submitted
+
+         Pull request review added.
+
+      .. value:: dismissed
+
+         Pull request review removed.
+
+   .. attr:: branch
+
+      The branch associated with the event. Example: ``master``.  This
+      field is treated as a regular expression, and multiple branches
+      may be listed. Used for ``pull_request`` and
+      ``pull_request_review`` events.
+
+   .. attr:: comment
+
+      This is only used for ``pull_request`` ``comment`` actions.  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 pull request.
+
+   .. attr:: label
+
+      This is only used for ``labeled`` and ``unlabeled``
+      ``pull_request`` actions.  It accepts a list of strings each of
+      which matches the label name in the event literally.  ``label:
+      recheck`` will match a ``labeled`` action when pull request is
+      labeled with a ``recheck`` label. ``label: 'do not test'`` will
+      match a ``unlabeled`` action when a label with name ``do not
+      test`` is removed from the pull request.
+
+   .. attr:: state
+
+      This is only used for ``pull_request_review`` events.  It
+      accepts a list of strings each of which is matched to the review
+      state, which can be one of ``approved``, ``comment``, or
+      ``request_changes``.
+
+   .. attr:: status
+
+      This is used for ``pull-request`` and ``status`` actions. It
+      accepts a list of strings each of which matches the user setting
+      the status, the status context, and the status itself in the
+      format of ``user:context:status``.  For example,
+      ``zuul_github_ci_bot:check_pipeline:success``.
+
+   .. attr:: ref
+
+      This is only used for ``push`` events. This field is treated as
+      a regular expression and multiple refs may be listed. GitHub
+      always sends full ref name, eg. ``refs/tags/bar`` and this
+      string is matched against the regular expression.
 
 Reporter Configuration
 ----------------------
@@ -166,38 +220,51 @@
 failure, an issue label addition/removal on the PR, and a merge of the PR
 itself. Status name, description, and context is taken from the pipeline.
 
-A :ref:`connection<connections>` that uses the github driver must be
-supplied to the reporter. It has the following options:
+.. attr:: pipeline.<reporter>.<github source>
 
-**status**
-  String value (``pending``, ``success``, ``failure``) that the
-  reporter should set as the commit status on github.  ``status:
-  'success'``
+   To report to GitHub, the dictionaries passed to any of the pipeline
+   :ref:`reporter<reporters>` attributes support the following
+   attributes:
 
-**status-url**
-  String value for a link url to set in the github status. Defaults to
-  the zuul server status_url, or the empty string if that is unset.
+   .. attr:: status
 
-**comment**
-  Boolean value (``true`` or ``false``) that determines if the
-  reporter should add a comment to the pipeline status to the github
-  pull request. Defaults to ``true``. Only used for Pull Request based
-  events.  ``comment: false``
+      String value (``pending``, ``success``, ``failure``) that the
+      reporter should set as the commit status on github.
 
-**merge**
-  Boolean value (``true`` or ``false``) that determines if the
-  reporter should merge the pull reqeust. Defaults to ``false``. Only
-  used for Pull Request based events.  ``merge=true``
+   .. TODO support role markup in :default: so we can xref
+      :attr:`webapp.status_url` below
 
-**label**
-  List of strings each representing an exact label name which should
-  be added to the pull request by reporter. Only used for Pull Request
-  based events.  ``label: 'test successful'``
+   .. attr:: status-url
+      :default: webapp.status_url or the empty string
 
-**unlabel**
-  List of strings each representing an exact label name which should
-  be removed from the pull request by reporter. Only used for Pull
-  Request based events.  ``unlabel: 'test failed'``
+      String value for a link url to set in the github
+      status. Defaults to the zuul server status_url, or the empty
+      string if that is unset.
+
+   .. attr:: comment
+      :default: true
+
+      Boolean value that determines if the reporter should add a
+      comment to the pipeline status to the github pull request. Only
+      used for Pull Request based items.
+
+   .. attr:: merge
+      :default: false
+
+      Boolean value that determines if the reporter should merge the
+      pull reqeust. Only used for Pull Request based items.
+
+   .. attr:: label
+
+      List of strings each representing an exact label name which
+      should be added to the pull request by reporter. Only used for
+      Pull Request based items.
+
+   .. attr:: unlabel
+
+      List of strings each representing an exact label name which
+      should be removed from the pull request by reporter. Only used
+      for Pull Request based items.
 
 .. _Github App: https://developer.github.com/apps/
 
@@ -208,7 +275,7 @@
 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 GitHub source named *my-github*, create a congfiguration such
+from a GitHub source named ``my-github``, create a congfiguration such
 as the following::
 
   pipeline:
@@ -218,7 +285,7 @@
           - type: approval
 
 This indicates that changes originating from the GitHub connection
-named *my-github* must have an approved code review in order to be
+named ``my-github`` must have an approved code review in order to be
 enqueued into the pipeline.
 
 .. attr:: pipeline.require.<github source>
@@ -292,7 +359,6 @@
       A string value indicating that the pull request must have the
       indicated label (or labels).
 
-
 .. attr:: pipeline.reject.<github source>
 
    The `reject` attribute is the mirror of the `require` attribute.  It