From 55d0c6fc5351e3b16697b82b5d9df5a353b77b27 Mon Sep 17 00:00:00 2001
From: Ian Wienand <iwienand@redhat.com>
Date: Thu, 19 Jul 2018 13:19:54 +1000
Subject: [PATCH] Use webhook update for docs-on-readthedocs

Update the docs-on-readthedocs template to use the new
trigger-readthedocs-webhook job.

This new job triggers readthedocs via their authenticated webhook API.
It is not a drop-in replacement; users will have to update with a API
key per the documentation (this will be communicated before merge;
however, note that the old API is not working).

For more details, see the comments in the dependent project-config
change.

The ability to have variables in templates is also new, see the
dependent zuul change.

Change-Id: I3b65813671961d07c0a743685c537ad1df4bf682
Depends-On: https://review.openstack.org/583449
Depends-On: https://review.openstack.org/584230
---
 zuul.d/project-templates.yaml | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/zuul.d/project-templates.yaml b/zuul.d/project-templates.yaml
index eff90557..7d1d1109 100644
--- a/zuul.d/project-templates.yaml
+++ b/zuul.d/project-templates.yaml
@@ -542,9 +542,30 @@
 - project-template:
     name: docs-on-readthedocs
     description: |
-      Runs normal OpenStack PTI build jobs but publishes to readthedocs
-      instead of docs.openstack.org. This is intended for projects that are
-      aiming to follow the PTI but are not official.
+      Runs normal OpenStack PTI build jobs but publishes to
+      `readthedocs <https://readthedocs.org>`__ instead of
+      `docs.openstack.org <https://docs.openstack.org>`__. This is
+      intended for projects that are aiming to follow the PTI but are
+      not official.
+
+      To use this template you need to:
+
+      #. add the ``openstackci`` user as an admin to your RTD project
+      #. generate a webhook URL via the "Integrations" dashboard page
+      #. provide the ``id`` in the ``rtd_webhook_id`` variable in your project
+
+      For example
+
+      .. code-block:: yaml
+
+        project:
+          name: openstack-project
+          description: My Project
+          templates:
+            - docs-on-readthedocs
+          vars:
+            rtd_webhook_id: '1234'
+
     check:
       jobs:
         - build-openstack-sphinx-docs
@@ -553,13 +574,13 @@
         - build-openstack-sphinx-docs
     post:
       jobs:
-        - trigger-readthedocs
+        - trigger-readthedocs-webhook
     pre-release:
       jobs:
-        - trigger-readthedocs
+        - trigger-readthedocs-webhook
     release:
       jobs:
-        - trigger-readthedocs
+        - trigger-readthedocs-webhook
 
 - project-template:
     name: nodejs4-publish-to-npm