Add warning job about readthedocs publishing

The readthedocs transition is slightly painful because it requires
readthedocs project owners to add infra to their projects, so we can
not do the update on their behalf.  Not everyone reads the mailing
list, and because the jobs run in the post pipeline it is very easily
missed that the publishing isn't actually happening.

Add a fake, non-voting, always failing job that should attract
attention.  Make a new template which we can switch failing projects
to; which they can easily switch back from in the same change that
adds the extra info required to make the jobs work.

Change-Id: I1866b8b00891caa0e6d9cde99555be8b55792e38

playbooks/docs/rtd-warning-job.yaml

@@ -0,0 +1,7 @@
+- hosts: all
+  tasks:
+    - name: Fail job
+      fail:
+        msg: |
+          Your project requires manual intervention to correctly publish results
+          to readthedocs.  For more details see http://lists.openstack.org/pipermail/openstack-dev/2018-August/132836.html

zuul.d/jobs.yaml

@@ -262,6 +262,14 @@
     vars:
       constraints_file: '{{ ansible_user_dir }}/src/git.openstack.org/openstack/requirements/upper-constraints.txt'
 
+- job:
+    name: your-readthedocs-job-requires-attention
+    parent: base
+    description: |
+      A placeholder job to warn projects their readthedocs
+      post-pipeline jobs are failing and require updating
+    run: playbooks/docs/rtd-warning-job.yaml
+
 - job:
     name: tox-py35-on-zuul
     parent: tox-py35

zuul.d/project-templates.yaml

@@ -686,6 +686,32 @@
       jobs:
         - trigger-readthedocs-webhook
 
+- project-template:
+    name: docs-on-readthedocs-failing
+    description: |
+      Template for projects requiring updates to their
+      docs-on-readthedocs usage.  Because project managers
+      are required to update their project, infra can not
+      fix deployment.  Since rtd triggering only
+      happens in the post pipeline, nobody really checks the
+      results of the jobs.  Not everyone reads the mailing list as
+      closely as we might like.  The result is a lot of projects
+      with broken documentation publishing that don't know about it.
+
+      This job always fails and provides a link to the mailing list
+      post with details of how to fix the job.
+
+      Revert to docs-on-readthedocs when the webhook id is added to
+      the project.
+    check:
+      jobs:
+        - build-openstack-sphinx-docs
+        - your-readthedocs-job-requires-attention:
+            voting: false
+    gate:
+      jobs:
+        - build-openstack-sphinx-docs
+
 - project-template:
     name: nodejs4-publish-to-npm
     post: