Add docs templates

Add project-templates for:
* Building documents
* Building documents and publishing them after each change

Use the new publish project-template for this repo, put the config in a
separate file to find it easier.

Update description of opendev-promote-docs.

Change-Id: Id76a751feb152afe8fca0893d9e0013440c51401

zuul.d/jobs.yaml

@@ -363,6 +363,12 @@
 
       Use this in the promote pipeline to publish a branch tip tarball
       built in the gate pipeline.
+
+      The documentation tarball is published to
+      https://docs.opendev.org/{{ zuul.project.name }}.
+
+      Publishes depending on branch to latest/ (for master), or the
+      basename of the branch like train (for stable/train).
     vars:
       download_artifact_job: opendev-tox-docs
     secrets:
@@ -461,18 +467,3 @@
     secrets:
       - secret: opendev-pypi
         name: pypi_info
-
-- project:
-    check:
-      jobs:
-        - opendev-tox-docs
-        - tox-linters:
-            required-projects: zuul/zuul-jobs
-    gate:
-      jobs:
-        - opendev-tox-docs
-        - tox-linters:
-            required-projects: zuul/zuul-jobs
-    promote:
-      jobs:
-        - opendev-promote-docs

zuul.d/project-templates.yaml

@@ -0,0 +1,28 @@
+- project-template:
+    name: build-opendev-tox-docs
+    description: |
+      Build documentation with "tox".
+    check:
+      jobs:
+        - opendev-tox-docs
+    gate:
+      jobs:
+        - opendev-tox-docs
+
+- project-template:
+    name: publish-opendev-tox-docs
+    description: |
+      Build and publish documentation with "tox".
+
+      The documents that are build in the "gate" pipeline
+      are published via a promote job to
+      https://docs.opendev.org/{{ zuul.project.name }}.
+    check:
+      jobs:
+        - opendev-tox-docs
+    gate:
+      jobs:
+        - opendev-tox-docs
+    promote:
+      jobs:
+        - opendev-promote-docs

zuul.d/project.yaml

@@ -0,0 +1,11 @@
+- project:
+    templates:
+      - publish-opendev-tox-docs
+    check:
+      jobs:
+        - tox-linters:
+            required-projects: zuul/zuul-jobs
+    gate:
+      jobs:
+        - tox-linters:
+            required-projects: zuul/zuul-jobs