Document jobs

Add inline documentation to jobs and render it in the jobs doc page.
Adjust the roles page to match jobs for title and filename.

Change-Id: I47a2b4b379c8517b0dea59a75943f3f871c29046

.zuul.yaml

@@ -163,6 +163,25 @@
       Base devstack job for integration gate.
 
       This base job can be used for single node and multinode devstack jobs.
+
+      With a single node nodeset, this job sets up an "all-in-one" (aio)
+      devstack with the six OpenStack services included in the devstack tree:
+      keystone, glance, cinder, neutron, nova and swift.
+
+      With a two node nodeset, this job sets up an aio + compute node.
+      The controller can be customised using host-vars.controller, the
+      sub-nodes can be customised using group-vars.subnode.
+
+      Descendent jobs can enable / disable services, add devstack configuration
+      options, enable devstack plugins, configure log files or directories to be
+      transferred to the log server.
+
+      The job assumes that there is only one controller node. The number of
+      subnodes can be scaled up seamlessly by setting a custom nodeset in
+      job.nodeset.
+
+      The run playbook consists of a single role, so it can be easily rewritten
+      and extended.
     nodeset: openstack-single-node
     required-projects:
       - openstack/cinder

doc/source/index.rst

@@ -139,7 +139,8 @@ up to date to the latest devstack).
 Enable :doc:`devstack plugins <plugins>` to support additional
 services, features, and configuration not present in base devstack.
 
-Use devstack in your CI with :doc:`Ansible roles <roles>` for Zuul V3.
+Use devstack in your CI with :doc:`Ansible roles <zuul_roles>` and
+:doc:`Jobs <zuul_jobs>` for Zuul V3.
 
 Get :doc:`the big picture <overview>` of what we are trying to do
 with devstack, and help us by :doc:`contributing to the project

doc/source/roles.rst

@@ -1,4 +0,0 @@
-Roles
-=====
-
-.. zuul:autoroles::

doc/source/zuul_jobs.rst

@@ -0,0 +1,4 @@
+Zuul CI Jobs
+============
+
+.. zuul:autojobs::

doc/source/zuul_roles.rst

@@ -0,0 +1,4 @@
+Zuul CI Roles
+=============
+
+.. zuul:autoroles::