Docs: move project config docs to user reference

Make a new user reference section and move project config docs there.

The bulk of our current documentation is, in fact, this user reference,
and it is currently hidden in the catch-all reference section.  Make
a user reference section so that Zuul users can easily find the
reference documentation most useful to them and move it there.

Some other minor tweaks are made to the individual config object
docs, so that if a user clicks on "User Reference" they will see
a page with a TOC that enumerates the config objects.

Change-Id: I48546a160b1ae9098ab903c46567b35e2f2bef7d

doc/source/index.rst

@@ -28,11 +28,8 @@ Zuul Users
    :maxdepth: 2
 
    tutorials/users/index
-
-.. toctree::
-   :maxdepth: 2
-
    howtos/users/index
+   reference/users/index
 
 Zuul Admins
 ***********
@@ -41,10 +38,6 @@ Zuul Admins
    :maxdepth: 2
 
    tutorials/admins/index
-
-.. toctree::
-   :maxdepth: 2
-
    howtos/admins/index
 
 Digging Deeper

doc/source/reference/index.rst

@@ -4,15 +4,6 @@ Reference
 .. toctree::
    :maxdepth: 2
 
-   config
-   pipeline_def
-   project_def
-   job_def
-   secret_def
-   nodeset_def
-   semaphore_def
-   pragma_def
-   jobs
    connections
    client
    monitoring

doc/source/reference/users/config.rst

@@ -80,10 +80,13 @@ example using number prefixes in file's names::
 Below are references to the different configuration items you may use within
 the YAML files:
 
-* :ref:`pipeline`
-* :ref:`project` and :ref:`project-template`
-* :ref:`job`
-* :ref:`secret`
-* :ref:`nodeset`
-* :ref:`semaphore`
-* :ref:`pragma`
+.. toctree::
+   :maxdepth: 1
+
+   pipeline_def
+   job_def
+   project_def
+   secret_def
+   nodeset_def
+   semaphore_def
+   pragma_def

doc/source/reference/users/index.rst

@@ -0,0 +1,8 @@
+User Reference
+==============
+
+.. toctree::
+   :maxdepth: 3
+
+   config
+   jobs

doc/source/reference/users/job_def.rst

@@ -1,10 +1,7 @@
-Job Definition
-==============
-
 .. _job:
 
 Job
-~~~
+===
 
 A job is a unit of work performed by Zuul on an item enqueued into a
 pipeline.  Items may run any number of jobs (which may depend on each
@@ -839,4 +836,3 @@ Here is an example of two job definitions:
       This means that changes to jobs with file matchers will be
       self-testing without requiring that the file matchers include
       the Zuul configuration file defining the job.
-

doc/source/reference/users/nodeset_def.rst

@@ -1,10 +1,7 @@
-Nodeset Definition
-==================
-
 .. _nodeset:
 
 Nodeset
-~~~~~~~
+=======
 
 A Nodeset is a named collection of nodes for use by a job.  Jobs may
 specify what nodes they require individually, however, by defining

doc/source/reference/users/pipeline_def.rst

@@ -1,10 +1,7 @@
-Pipeline Definition
-===================
-
 .. _pipeline:
 
 Pipeline
-~~~~~~~~
+========
 
 A pipeline describes a workflow operation in Zuul.  It associates jobs
 for a given project with triggering and reporting events.
@@ -411,4 +408,3 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       <pipeline.manager.dependent>` only. The value to be subtracted
       or divided against the previous window value to determine the
       new window after unsuccessful change merges.
-

doc/source/reference/users/pragma_def.rst

@@ -1,10 +1,7 @@
-Pragma Definition
-=================
-
 .. _pragma:
 
 Pragma
-~~~~~~
+======
 
 The `pragma` item does not behave like the others.  It can not be
 included or excluded from configuration loading by the administrator,

doc/source/reference/users/project_def.rst

@@ -1,10 +1,7 @@
-Project and Project Template Definition
-=======================================
-
 .. _project:
 
 Project
-~~~~~~~
+=======
 
 A project corresponds to a source code repository with which Zuul is
 configured to interact.  The main responsibility of the project
@@ -69,27 +66,6 @@ The ``gate`` project-pipeline definition above specifies that this
 project participates in the ``integrated`` shared queue for that
 pipeline.
 
-.. _project-template:
-
-Project Template
-~~~~~~~~~~~~~~~~
-
-A Project Template defines one or more project-pipeline definitions
-which can be re-used by multiple projects.
-
-A Project Template uses the same syntax as a :ref:`project`
-definition, however, in the case of a template, the
-:attr:`project.name` attribute does not refer to the name of a
-project, but rather names the template so that it can be referenced in
-a :ref:`project` definition.
-
-Because Project Templates may be used outside of the projects where
-they are defined, they honor the implied branch :ref:`pragmas <pragma>`
-(unlike Projects).  The same heuristics described in
-:attr:`job.branches` that determine what implied branches a :ref:`job`
-will receive apply to Project Templates (with the exception that it is
-not possible to explicity set a branch matcher on a Project Template).
-
 .. attr:: project
 
    The following attributes may appear in a project:
@@ -234,3 +210,23 @@ not possible to explicity set a branch matcher on a Project Template).
          can be forced to a specific value by e.g. defining it in a config
          repo.
 
+.. _project-template:
+
+Project Template
+================
+
+A Project Template defines one or more project-pipeline definitions
+which can be re-used by multiple projects.
+
+A Project Template uses the same syntax as a :ref:`project`
+definition, however, in the case of a template, the
+:attr:`project.name` attribute does not refer to the name of a
+project, but rather names the template so that it can be referenced in
+a :ref:`project` definition.
+
+Because Project Templates may be used outside of the projects where
+they are defined, they honor the implied branch :ref:`pragmas <pragma>`
+(unlike Projects).  The same heuristics described in
+:attr:`job.branches` that determine what implied branches a :ref:`job`
+will receive apply to Project Templates (with the exception that it is
+not possible to explicity set a branch matcher on a Project Template).

doc/source/reference/users/secret_def.rst

@@ -1,10 +1,7 @@
-Secret Definition
-=================
-
 .. _secret:
 
 Secret
-~~~~~~
+======
 
 A Secret is a collection of private data for use by one or more jobs.
 In order to maintain the security of the data, the values are usually
@@ -95,4 +92,3 @@ branch will not immediately produce a configuration error.
       available to the job.  The values can be any of the normal YAML
       data types (strings, integers, dictionaries or lists) or
       encrypted strings.  See :ref:`encryption` for more information.
-

doc/source/reference/users/semaphore_def.rst

@@ -1,10 +1,7 @@
-Semaphore Definition
-====================
-
 .. _semaphore:
 
 Semaphore
-~~~~~~~~~
+=========
 
 Semaphores can be used to restrict the number of certain jobs which
 are running at the same time.  This may be useful for jobs which