Refactor the common-view and csit-view template

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

diff --git a/docs/jjb/lf-views.rst b/docs/jjb/lf-views.rst
index 926ba59..7ed4936 100644 (file)
--- a/docs/jjb/lf-views.rst
+++ b/docs/jjb/lf-views.rst
@@ -7,14 +7,59 @@ Jenkins Views
 View Templates
 ==============
 
-JJB view-templates provides a way to manage Jenkins views through code.
+JJB view-templates provides a way to manage Jenkins views through code. Using
+view-templates we can define common views configuration that are interesting
+to a project.
 
+We recommend creating separate project sections for views apart from job
+configuration such that job configuration does not overlap with the view
+configuration.
+
+Example Usage:
+
+.. code-block:: yaml
+
+   ---
+   - project:
+       name: project-view
+       views:
+         - common-view
+
+       project-name: project
+
+   - project:
+       name: project-stream1
+       jobs:
+         - '{project-name}-{seq}'
+
+       project: project
+       project-name: project
+       seq:
+         - a
+         - b
+
+   - project:
+       name: project-stream2
+       jobs:
+         - '{project-name}-{seq}'
+
+       project: project
+       project-name: project
+       seq:
+         - x
+         - y
+
+   - job-template:
+       name: '{project-name}-{seq}'
 
-Common view
------------
 
-Common view groups jobs related to a project and supports the following
-columns.
+Project view
+------------
+
+Groups all jobs owned by a project under one view by capturing jobs with the
+prefix of ``project-name``.
+
+This view uses the following columns:
 
 :Columns:
 
@@ -27,20 +72,15 @@ columns.
     - build-button
     - jacoco
     - find-bugs
-    - robot-list
 
 :Template Names:
 
-    - common-view
     - {project-name}
+    - project-view
 
 :Required parameters:
 
-    :project-name: The name of the view.
-    :view-description: View description. (Generally set to 'List of
-        {project-name} jobs' in defaults.yaml)
-    :view-regex: Regex to match the jobs. (Generally set to '^{project-name}-.*'
-        in defaults.yaml)
+    :project-name: The name of the project utilizing the view.
 
 :Optional parameters:
 
@@ -48,11 +88,60 @@ columns.
     :view-filter-queue: View filter queue. (default: false)
     :view-recurse: View recurse. (default: false)
 
-Integration CSIT view
----------------------
+Example:
+
+.. literalinclude:: ../../.jjb-test/lf-project-view.yaml
+   :language: yaml
+
 
-Integration CSIT view provides a view for integration or CSIT jobs.
-The view supports the following set of columns.
+Common view
+-----------
+
+Groups all jobs owned by a project under one view by capturing jobs with the
+prefix of ``project-name``.
+
+This view uses the following columns:
+
+:Columns:
+
+   - status
+   - weather
+   - job
+   - last-success
+   - last-failure
+   - last-duration
+   - build-button
+   - jacoco
+   - find-bugs
+
+:Template Names:
+
+   - {view-name}
+   - common-view
+
+:Required parameters:
+
+   :view-name: The name of the view.
+   :view-regex: Regex to match the jobs.
+
+:Optional parameters:
+
+   :view-filter-executors: View filter executor. (default: false)
+   :view-filter-queue: View filter queue. (default: false)
+   :view-recurse: View recurse. (default: false)
+
+Example:
+
+.. literalinclude:: ../../.jjb-test/lf-common-view.yaml
+  :language: yaml
+
+
+CSIT view template
+------------------
+
+View template that loads columns useful for CSIT jobs.
+
+This view uses the following columns:
 
 :Columns:
 
@@ -67,19 +156,22 @@ The view supports the following set of columns.
 
 :Template Names:
 
-    - integration-csit-view
-    - {project-name}
+    - {view-name}
+    - csit-view
 
 :Required parameters:
 
-    :project-name: The name of the view.
-    :view-description: View description. (Generally set to 'List of
-        {project-name} jobs' in defaults.yaml)
-    :view-regex: Regex to match the jobs. (Generally set to '^{project-name}-.*'
-        in defaults.yaml)
+    :view-name: The name of the view.
+    :view-regex: Regex to match the jobs.
 
 :Optional parameters:
 
+    :view-description: View description. (default: 'CSIT Jobs.')
     :view-filter-executors: View filter executor. (default: false)
     :view-filter-queue: View filter queue. (default: false)
     :view-recurse: View recurse. (default: false)
+
+Example:
+
+.. literalinclude:: ../../.jjb-test/lf-csit-view.yaml
+   :language: yaml