Update RTD to use custom trigger url

[releng/global-jjb.git] / docs / jjb / lf-rtd-jobs.rst

diff --git a/docs/jjb/lf-rtd-jobs.rst b/docs/jjb/lf-rtd-jobs.rst
index 66181a4..2b3500e 100644 (file)
--- 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
 ################
@@ -6,9 +8,9 @@ Job Groups
 ==========
 
 {project-name}-rtd-jobs
-----------------------
+-----------------------
 
-Jobs that should be deployed for a project producing ReadTheDocs using Gerrit.
+Jobs to deploy for a project producing ReadTheDocs using Gerrit.
 
 :Includes:
 
@@ -16,9 +18,9 @@ Jobs that should be deployed for a project producing ReadTheDocs using Gerrit.
     - gerrit-rtd-verify
 
 {project-name}-github-rtd-jobs
------------------------------
+------------------------------
 
-Jobs that should be deployed for a project producing ReadTheDocs using GitHub.
+Jobs to deploy for a project producing ReadTheDocs using GitHub.
 
 :Includes:
 
@@ -42,7 +44,18 @@ 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.  There is some setup
+required on read the docs to get started with this.  After you have created the
+individual read the docs project (lets call it "PROJECT" here), then browse to
+https://readthedocs.org/dashboard/PROJECT/integrations/ and click on
+"Generic API incoming webhook".  Here you will see a custom url to trigger the job as
+well as a token.  Persist the token in the project Jenkins global-settings
+file.  You will need to put it in a username/password credentials type to make
+it available in the global-settings file.  set ```rtd-build-url to the
+custom build url as defined in read the docs.  Also set the rtd-server-id
+to the id you specified in the global-settings file, this will enable the script to parse
+the token out. Set ```rtd-project``` to your read the docs project name.
+
 
 :Template Names:
     - {project-name}-rtd-merge-{stream}
@@ -52,9 +65,14 @@ Merge job which triggers a POST of the docs project to readthedocs
 :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)
     :rtd-project: This is the name of the project on ReadTheDocs.org.
+    :rtd-build-url: This is the generic webhook url from readthedocs.org
+    :global-settings-file: This is the location of the Jenkins global settings file.
+        This file contains the entry with the location for the readthedocs build token.
+    :rtd-server-id: This is the id of the entry in the global-settings-file.
+
 
 :Optional parameters:
 
@@ -62,15 +80,15 @@ Merge job which triggers a POST of the docs project to readthedocs
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in seconds 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
@@ -92,8 +110,8 @@ Verify job which runs a tox build of the docs project
 :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:
 
@@ -104,15 +122,15 @@ Verify job which runs a tox build of the docs project
     :doc-dir: Directory where tox will place built docs.
         as defined in the tox.ini (default: docs/_build/html)
     :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