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