From 3db8a08c140f77574447e508a2070043400826af Mon Sep 17 00:00:00 2001
From: Andreas Jaeger <aj@suse.com>
Date: Fri, 10 Aug 2018 17:41:18 +0200
Subject: [PATCH] enhance publish-openstack-sphinx-docs description

Link to Doc contributor guide on how to add something to the main index
and also explain that docs.o.o is for official projects only.

Update some doc templates, since the PTI has changed we now have legacy
jobs and new PTI ones.

Change-Id: I933628d3864dd3d706831985efbc12ac413812dc
---
 zuul.d/project-templates.yaml | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/zuul.d/project-templates.yaml b/zuul.d/project-templates.yaml
index ab5c773e..e1ae817d 100644
--- a/zuul.d/project-templates.yaml
+++ b/zuul.d/project-templates.yaml
@@ -26,7 +26,10 @@
 - project-template:
     name: build-openstack-sphinx-docs
     description: |
-      Runs normal OpenStack PTI doc build without publication jobs.
+      Runs legacy OpenStack doc build without publication jobs.
+
+      This template is deprecated and should only be used for older stable
+      branches.
     check:
       jobs:
         - build-openstack-sphinx-docs
@@ -37,9 +40,12 @@
 - project-template:
     name: build-openstack-sphinx-docs-python3
     description: |
-      Runs normal OpenStack PTI doc build without publication jobs.
+      Runs legacy OpenStack doc build without publication jobs.
 
       Builds the docs using Sphinx with Python3.
+
+      This template is deprecated and should only be used for older stable
+      branches.
     check:
       jobs:
         - build-openstack-sphinx-docs:
@@ -54,7 +60,10 @@
 - project-template:
     name: publish-openstack-sphinx-docs
     description: |
-      Runs normal OpenStack PTI doc build and publication jobs.
+      Runs legacy OpenStack doc build and publication jobs.
+
+      This template is deprecated and should only be used for older stable
+      branches.
     check:
       jobs:
         - build-openstack-sphinx-docs
@@ -68,9 +77,21 @@
 - project-template:
     name: publish-openstack-docs-pti
     description: |
-      Runs normal OpenStack PTI doc build and publication jobs
+      Runs normal `OpenStack PTI documentation build and publication jobs
+      <https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation>`_
       following the project testing interface.
 
+      Once you have docs published, add them to the index pages
+      following the `documentation
+      <https://docs.openstack.org/doc-contrib-guide/doc-index.html>`_
+      .
+
+      .. note::
+
+         Only repos listed in ``openstack/governance`` repository are
+         allowed to publish to the `OpenStack docs website
+         <https://docs.openstack.org>`_ .
+
     check:
       jobs:
         - openstack-tox-docs