Reorganize docs into user/admin guide
Refresh the user and admin guide for v3 changes, and reorganize into
a narrative structure which makes more sense for v3.
Change-Id: I4ac3b18d5ed33b0fea4e2ef0318b19bfc3447ccc
diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
new file mode 100644
index 0000000..6cd2f3d
--- /dev/null
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -0,0 +1,168 @@
+:title: Gerrit Driver
+
+Gerrit
+======
+
+`Gerrit`_ is a code review system. The Gerrit driver supports
+sources, triggers, and reporters.
+
+.. _Gerrit: https://www.gerritcodereview.com/
+
+Zuul will need access to a Gerrit user.
+
+Create an SSH keypair for Zuul to use if there isn't one already, and
+create a Gerrit user with that key::
+
+ cat ~/id_rsa.pub | ssh -p29418 review.example.com gerrit create-account --ssh-key - --full-name Zuul zuul
+
+Give that user whatever permissions will be needed on the projects you
+want Zuul to report on. For instance, you may want to grant
+``Verified +/-1`` and ``Submit`` to the user. Additional categories
+or values may be added to Gerrit. Zuul is very flexible and can take
+advantage of those.
+
+Connection Configuration
+------------------------
+
+The supported options in zuul.conf connections are:
+
+**driver=gerrit**
+
+**server**
+ FQDN of Gerrit server.
+ ``server=review.example.com``
+
+**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 repos from this connection by name and in preparing repos
+ on the filesystem for use by jobs.
+ ``canonical_hostname=git.example.com``
+
+**port**
+ Optional: Gerrit server port.
+ ``port=29418``
+
+**baseurl**
+ Optional: path to Gerrit web interface. Defaults to ``https://<value
+ of server>/``. ``baseurl=https://review.example.com/review_site/``
+
+**user**
+ User name to use when logging into above server via ssh.
+ ``user=zuul``
+
+**sshkey**
+ Path to SSH key to use when logging into above server.
+ ``sshkey=/home/zuul/.ssh/id_rsa``
+
+**keepalive**
+ Optional: Keepalive timeout, 0 means no keepalive.
+ ``keepalive=60``
+
+Trigger Configuration
+---------------------
+
+Zuul works with standard versions of Gerrit by invoking the ``gerrit
+stream-events`` command over an SSH connection. It also reports back
+to Gerrit using SSH.
+
+If using Gerrit 2.7 or later, make sure the user is a member of a group
+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:
+
+**event**
+The event name from gerrit. Examples: ``patchset-created``,
+``comment-added``, ``ref-updated``. This field is treated as a
+regular expression.
+
+**branch**
+The branch associated with the event. Example: ``master``. This
+field is treated as a regular expression, and multiple branches may
+be listed.
+
+**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.
+
+**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.
+
+**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.
+
+**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$``.
+
+**email_filter** (deprecated)
+A deprecated alternate spelling of *email*. Only one of *email* or
+*email_filter* should be used.
+
+**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$``.
+
+**username_filter** (deprecated)
+A deprecated alternate spelling of *username*. Only one of *username* or
+*username_filter* should be used.
+
+**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.
+
+**comment_filter** (deprecated)
+A deprecated alternate spelling of *comment*. Only one of *comment* or
+*comment_filter* should be used.
+
+*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 the :ref:`"approval" pipeline requirement
+<pipeline-require-approval>`. For each specified criteria there must
+exist a matching approval.
+
+*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.
+
+Reporter Configuration
+----------------------
+
+Zuul works with standard versions of Gerrit by invoking the
+``gerrit`` command over an SSH connection. It reports back to
+Gerrit using SSH.
+
+The dictionary passed to the Gerrit reporter is used for ``gerrit
+review`` arguments, with the boolean value of ``true`` simply
+indicating that the argument should be present without following it
+with a value. For example, ``verified: 1`` becomes ``gerrit review
+--verified 1`` and ``submit: true`` becomes ``gerrit review
+--submit``.
+
+A :ref:`connection<connections>` that uses the gerrit driver must be
+supplied to the trigger.
diff --git a/doc/source/admin/drivers/github.rst b/doc/source/admin/drivers/github.rst
new file mode 100644
index 0000000..cc2a5c9
--- /dev/null
+++ b/doc/source/admin/drivers/github.rst
@@ -0,0 +1,162 @@
+:title: GitHub Driver
+
+GitHub
+======
+
+The GitHub driver supports sources, triggers, and reporters. It can
+interact with the public GitHub service as well as site-local
+installations of GitHub enterprise.
+
+.. TODO: make this section more user friendly
+
+Configure GitHub `webhook events
+<https://developer.github.com/webhooks/creating/>`_.
+
+Set *Payload URL* to
+``http://<zuul-hostname>/connection/<connection-name>/payload``.
+
+Set *Content Type* to ``application/json``.
+
+Select *Events* you are interested in. See below for the supported events.
+
+Connection Configuration
+------------------------
+
+The supported options in zuul.conf connections are:
+
+**driver=github**
+
+**api_token**
+ API token for accessing GitHub.
+ See `Creating an access token for command-line use
+ <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
+
+**webhook_token**
+ Optional: Token for validating the webhook event payloads.
+ If not specified, payloads are not validated.
+ See `Securing your webhooks
+ <https://developer.github.com/webhooks/securing/>`_.
+
+**sshkey**
+ Path to SSH key to use when cloning github repositories.
+ ``sshkey=/home/zuul/.ssh/id_rsa``
+
+**git_host**
+ Optional: Hostname of the github install (such as a GitHub Enterprise)
+ If not specified, defaults to ``github.com``
+ ``git_host=github.myenterprise.com``
+
+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.
+
+**event**
+The event from github. Supported events are ``pull_request``,
+``pull_request_review``, and ``push``.
+
+A ``pull_request`` event will
+have associated action(s) to trigger from. The supported actions are:
+
+ *opened* - pull request opened
+
+ *changed* - pull request synchronized
+
+ *closed* - pull request closed
+
+ *reopened* - pull request reopened
+
+ *comment* - comment added on pull request
+
+ *labeled* - label added on pull request
+
+ *unlabeled* - label removed from pull request
+
+ *status* - status set on commit
+
+A ``pull_request_review`` event will
+have associated action(s) to trigger from. The supported actions are:
+
+ *submitted* - pull request review added
+
+ *dismissed* - pull request review removed
+
+**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.
+
+**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.
+
+**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.
+
+**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``.
+
+**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``.
+
+**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.
+
+Reporter Configuration
+----------------------
+Zuul reports back to GitHub via GitHub API. Available reports include a PR
+comment containing the build results, a commit status on start, success and
+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:
+
+**status**
+String value (``pending``, ``success``, ``failure``) that the reporter should
+set as the commit status on github.
+``status: 'success'``
+
+**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.
+
+**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``
+
+**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``
+
+**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'``
+
+**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'``
diff --git a/doc/source/admin/drivers/smtp.rst b/doc/source/admin/drivers/smtp.rst
new file mode 100644
index 0000000..6f24355
--- /dev/null
+++ b/doc/source/admin/drivers/smtp.rst
@@ -0,0 +1,53 @@
+:title: SMTP Driver
+
+SMTP
+====
+
+The SMTP driver supports reporters only. It is used to send email
+when items report.
+
+Connection Configuration
+------------------------
+
+**driver=smtp**
+
+**server**
+ SMTP server hostname or address to use.
+ ``server=localhost``
+
+**port**
+ Optional: SMTP server port.
+ ``port=25``
+
+**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**
+ Who the report should be emailed to by default.
+ This can be overridden by individual pipelines.
+ ``default_to=you@example.com``
+
+Reporter Configuration
+----------------------
+
+A simple email reporter is also available.
+
+A :ref:`connection<connections>` that uses the smtp driver must be supplied to the
+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, ::
+
+ - pipeline:
+ name: post-merge
+ success:
+ outgoing_smtp:
+ to: you@example.com
+ failure:
+ internal_smtp:
+ to: you@example.com
+ from: alternative@example.com
+ subject: Change {change} failed
diff --git a/doc/source/admin/drivers/sql.rst b/doc/source/admin/drivers/sql.rst
new file mode 100644
index 0000000..b890f08
--- /dev/null
+++ b/doc/source/admin/drivers/sql.rst
@@ -0,0 +1,44 @@
+:title: SQL Driver
+
+SQL
+===
+
+The SQL driver supports reporters only. Only one connection per
+database is permitted. The connection options are:
+
+**driver=sql**
+
+**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``
+
+Reporter Configuration
+----------------------
+
+This reporter is used to store results in a database.
+
+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.
+
+The SQL reporter does nothing on "start" or "merge-failure"; it only
+acts on "success" or "failure" reporting stages.
+
+**score**
+ A score to store for the result of the build. eg: -1 might indicate a failed
+ build.
+
+For example ::
+
+ - pipeline:
+ name: post-merge
+ success:
+ mydb_conn:
+ score: 1
+ failure:
+ mydb_conn:
+ score: -1
diff --git a/doc/source/admin/drivers/timer.rst b/doc/source/admin/drivers/timer.rst
new file mode 100644
index 0000000..574ee1e
--- /dev/null
+++ b/doc/source/admin/drivers/timer.rst
@@ -0,0 +1,24 @@
+:title: Timer Driver
+
+Timer
+=====
+
+The timer driver supports triggers only. It is used for configuring
+pipelines so that jobs run at scheduled times. No connection
+configuration is required.
+
+Trgger Configuration
+--------------------
+
+Timers don't require a special connection or driver. Instead they can
+simply be used by listing **timer** as the trigger.
+
+This trigger will run based on a cron-style time specification.
+It will enqueue an event into its pipeline for every project
+defined in the configuration. Any job associated with the
+pipeline will run in response to that event.
+
+**time**
+The time specification in cron syntax. Only the 5 part syntax is
+supported, not the symbolic names. Example: ``0 0 * * *`` runs
+at midnight.
diff --git a/doc/source/admin/drivers/zuul.rst b/doc/source/admin/drivers/zuul.rst
new file mode 100644
index 0000000..a875457
--- /dev/null
+++ b/doc/source/admin/drivers/zuul.rst
@@ -0,0 +1,40 @@
+:title: Zuul Driver
+
+Zuul
+====
+
+The Zuul driver supports triggers only. It is used for triggering
+pipelines based on internal Zuul events.
+
+Trigger Configuration
+---------------------
+
+Zuul events don't require a special connection or driver. Instead they
+can simply be used by listing **zuul** as the trigger.
+
+**event**
+The event name. Currently supported:
+
+ *project-change-merged* when Zuul merges a change to a project,
+ it generates this event for every open change in the project.
+
+ *parent-change-enqueued* when Zuul enqueues a change into any
+ pipeline, it generates this event for every child of that
+ change.
+
+**pipeline**
+Only available for ``parent-change-enqueued`` events. This is the
+name of the pipeline in which the parent change was enqueued.
+
+*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 the :ref:`"approval" pipeline requirement
+<pipeline-require-approval>`. For each specified criteria there must
+exist a matching approval.
+
+*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.