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
diff --git a/.zuul.yaml b/.zuul.yaml
index 2ef23c8..693cd77 100644
--- a/.zuul.yaml
+++ b/.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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9254c23..4c53203 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -139,7 +139,8 @@
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
diff --git a/doc/source/roles.rst b/doc/source/roles.rst
deleted file mode 100644
index 5baa1e4..0000000
--- a/doc/source/roles.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Roles
-=====
-
-.. zuul:autoroles::
diff --git a/doc/source/zuul_jobs.rst b/doc/source/zuul_jobs.rst
new file mode 100644
index 0000000..cf203a8
--- /dev/null
+++ b/doc/source/zuul_jobs.rst
@@ -0,0 +1,4 @@
+Zuul CI Jobs
+============
+
+.. zuul:autojobs::
diff --git a/doc/source/zuul_roles.rst b/doc/source/zuul_roles.rst
new file mode 100644
index 0000000..4939281
--- /dev/null
+++ b/doc/source/zuul_roles.rst
@@ -0,0 +1,4 @@
+Zuul CI Roles
+=============
+
+.. zuul:autoroles::