X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-rtd-jobs.rst;h=b21cee6ecd4ef2c56d8069a871ccceef2b31db64;hb=refs%2Fchanges%2F61%2F12861%2F3;hp=66181a476ca900785304a90b76b9629e9a822f7c;hpb=391e8138f528a720604ed9da7bda949b5e56fbec;p=releng%2Fglobal-jjb.git

diff --git a/docs/jjb/lf-rtd-jobs.rst b/docs/jjb/lf-rtd-jobs.rst
index 66181a47..b21cee6e 100644
--- a/docs/jjb/lf-rtd-jobs.rst
+++ b/docs/jjb/lf-rtd-jobs.rst
@@ -1,3 +1,5 @@
+.. _lf-global-jjb-rtd-jobs:
+
 ################
 ReadTheDocs Jobs
 ################
@@ -5,25 +7,12 @@ ReadTheDocs Jobs
 Job Groups
 ==========
 
-{project-name}-rtd-jobs
-----------------------
-
-Jobs that should be deployed for a project producing ReadTheDocs using Gerrit.
-
-:Includes:
-
-    - gerrit-rtd-merge
-    - gerrit-rtd-verify
-
-{project-name}-github-rtd-jobs
------------------------------
-
-Jobs that should be deployed for a project producing ReadTheDocs using GitHub.
+.. include:: ../job-groups.rst
 
-:Includes:
+Below is a list of Maven job groups:
 
-    - github-rtd-merge
-    - github-rtd-verify
+.. literalinclude:: ../../jjb/lf-rtd-job-groups.yaml
+   :language: yaml
 
 
 Macros
@@ -42,35 +31,59 @@ Job Templates
 ReadTheDocs Merge
 -----------------
 
-Merge job which triggers a POST of the docs project to readthedocs
+Merge job which triggers a POST of the docs project to readthedocs.
+
+To use this job first configure the ``Generic API incoming webhook`` in
+ReadTheDocs. To do that follow these steps:
+
+#. Browse to https://readthedocs.org/dashboard/PROJECT/integrations/
+#. Click on ``Generic API incoming webhook``
+
+   .. note::
+
+      If not available click on ``Add integration`` and add the
+      ``Generic API incoming webhook``.
+
+#. Copy the custom webhook URL, this is your ``rtd-build-url``
+
+   For example: https://readthedocs.org/api/v2/webhook/opendaylight/32321/
+
+#. Copy the token, this is your ``rtd-token``
 
 :Template Names:
     - {project-name}-rtd-merge-{stream}
     - gerrit-rtd-merge
     - github-rtd-merge
 
+:Comment Trigger: remerge
+
 :Required parameters:
 
     :build-node: The node to run build on.
-    :jenkins-ssh-credential: Credential to use for SSH. (Generally should
-        be configured in defaults.yaml)
-    :rtd-project: This is the name of the project on ReadTheDocs.org.
+    :jenkins-ssh-credential: Credential to use for SSH. (Generally set
+        in defaults.yaml)
+    :rtd-build-url: This is the generic webhook url from readthedocs.org. Refer
+        to the above instructions to generate one.
+        (Check Admin > Integrations > Generic API incoming webhook)
+    :rtd-token: The unique token for the project Generic webhook. Refer
+        to the above instructions to generate one.
+        (Check Admin > Integrations > Generic API incoming webhook)
 
 :Optional parameters:
 
     :branch: Git branch to fetch for the build. (default: master)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
-    :build-timeout: Timeout in seconds before aborting build. (default: 15)
+    :build-timeout: Timeout in minutes before aborting build. (default: 15)
     :git-url: base URL of git project. (default: https://github.com)
-    :project-pattern: Project to trigger build against. (default: **)
-    :stream: Keyword that can be used to represent a release code-name.
+    :project-pattern: Project to trigger build against. (default: \*\*)
+    :stream: Keyword representing a release code-name.
         Often the same as the branch. (default: master)
     :submodule-recursive: Whether to checkout submodules recursively.
         (default: true)
 
     :gerrit_merge_triggers: Override Gerrit Triggers.
-    :gerrit_trigger_file_paths: Override file paths which can be used to
-        filter which file modifications will trigger a build.
+    :gerrit_trigger_file_paths: Override file paths filter which checks which
+        file modifications will trigger a build.
         **default**::
 
             - compare-type: ANT
@@ -89,30 +102,33 @@ Verify job which runs a tox build of the docs project
     - gerrit-rtd-verify
     - github-rtd-verify
 
+:Comment Trigger: recheck|reverify
+
 :Required Parameters:
 
     :build-node: The node to run build on.
-    :jenkins-ssh-credential: Credential to use for SSH. (Generally should
-        be configured in defaults.yaml)
+    :jenkins-ssh-credential: Credential to use for SSH. (Generally set
+        in defaults.yaml)
 
 :Optional Parameters:
 
     :branch: Git branch to fetch for the build. (default: master)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-node: The node to run build on.
-    :build-timeout: Timeout in seconds before aborting build. (default: 15)
+    :build-timeout: Timeout in minutes before aborting build. (default: 15)
     :doc-dir: Directory where tox will place built docs.
         as defined in the tox.ini (default: docs/_build/html)
+    :gerrit-skip-vote: Skip voting for this job. (default: false)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
-    :project-pattern: Project to trigger build against. (default: **)
-    :stream: Keyword that can be used to represent a release code-name.
+    :project-pattern: Project to trigger build against. (default: \*\*)
+    :stream: Keyword representing a release code-name.
         Often the same as the branch. (default: master)
     :submodule-recursive: Whether to checkout submodules recursively.
         (default: true)
 
     :gerrit_verify_triggers: Override Gerrit Triggers.
-    :gerrit_trigger_file_paths: Override file paths which can be used to
-        filter which file modifications will trigger a build.
+    :gerrit_trigger_file_paths: Override file paths filter which checks which
+        file modifications will trigger a build.
         **default**::
 
             - compare-type: ANT