Support additional features in Build Flow project

* Allow requiring a workspace.
* Allow running a DSL script from file.
* Adding job parameters documentation.

Change-Id: Ida71e40df3dd440d956b91005d932915bdb3d4f7

jenkins_jobs/modules/project_flow.py

@@ -26,6 +26,13 @@ In order to use it for job-template you have to escape the curly braces by
 doubling them in the DSL: { -> {{ , otherwise it will be interpreted by the
 python str.format() command.
 
+:Job Parameters:
+    * **dsl** (`str`): The DSL content. (optional)
+    * **needs-workspace** (`bool`): This build needs a workspace. \
+    (default false)
+    * **dsl-file** (`str`): Path to the DSL script in the workspace. \
+    Has effect only when `needs-workspace` is true. (optional)
+
 Job example:
 
     .. literalinclude::
@@ -36,6 +43,11 @@ Job template example:
     .. literalinclude::
       /../../tests/yamlparser/fixtures/project_flow_template002.yaml
 
+Job example runninng a DSL file from the workspace:
+
+    .. literalinclude::
+      /../../tests/yamlparser/fixtures/project_flow_template003.yaml
+
 """
 
 import xml.etree.ElementTree as XML
@@ -52,4 +64,11 @@ class Flow(jenkins_jobs.modules.base.Base):
         else:
             XML.SubElement(xml_parent, 'dsl').text = ''
 
+        needs_workspace = data.get('needs-workspace', False)
+        XML.SubElement(xml_parent, 'buildNeedsWorkspace').text = str(
+            needs_workspace).lower()
+
+        if needs_workspace and 'dsl-file' in data:
+            XML.SubElement(xml_parent, 'dslFile').text = data['dsl-file']
+
         return xml_parent

tests/general/fixtures/project-type003.xml

@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <com.cloudbees.plugins.flow.BuildFlow>
   <dsl/>
+  <buildNeedsWorkspace>false</buildNeedsWorkspace>
   <actions/>
   <keepDependencies>false</keepDependencies>
   <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>

tests/yamlparser/fixtures/project_flow_template001.xml

@@ -6,6 +6,7 @@ parallel (
   { build("job2b") }
 )
 </dsl>
+  <buildNeedsWorkspace>false</buildNeedsWorkspace>
   <actions/>
   <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
   <keepDependencies>false</keepDependencies>

tests/yamlparser/fixtures/project_flow_template002.xml

@@ -7,6 +7,7 @@ parallel (
 )
 build("job2c")
 </dsl>
+  <buildNeedsWorkspace>false</buildNeedsWorkspace>
   <actions/>
   <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
   <keepDependencies>false</keepDependencies>

tests/yamlparser/fixtures/project_flow_template003.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<com.cloudbees.plugins.flow.BuildFlow>
+  <dsl/>
+  <buildNeedsWorkspace>true</buildNeedsWorkspace>
+  <dslFile>script.groovy</dslFile>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <publishers/>
+  <buildWrappers/>
+</com.cloudbees.plugins.flow.BuildFlow>

tests/yamlparser/fixtures/project_flow_template003.yaml

@@ -0,0 +1,5 @@
+- job:
+      name: test_job
+      project-type: flow
+      needs-workspace: true
+      dsl-file: script.groovy