Update documentation for lazy-loaded files

Now, when tag !include-raw: has variable in included file path,
included file is expanded.
And lazy-loading mechanics is removed - now it can be expanded in
the usual way.

Change-Id: I7234d42793a080e7f4186707c4d1d2e9404bd7f3

jenkins_jobs/yaml_objects.py

@@ -143,34 +143,21 @@ For all the multi file includes, the files are simply appended using a newline
 character.
 
 
-To allow for job templates to perform substitution on the path names, when a
-filename containing a python format placeholder is encountered, lazy loading
-support is enabled, where instead of returning the contents back during yaml
-parsing, it is delayed until the variable substitution is performed.
+You can also use variables in included file paths.
 
 Example:
 
     .. literalinclude:: /../../tests/yamlparser/job_fixtures/lazy-load-jobs001.yaml
 
+    with variable substitution inside included files:
+
+    .. literalinclude:: /../../tests/yamlparser/job_fixtures/lazy-load-with-variables.yaml
+
     using a list of files:
 
     .. literalinclude::
         /../../tests/yamlparser/job_fixtures/lazy-load-jobs-multi001.yaml
 
-.. note::
-
-    Because lazy-loading involves performing the substitution on the file
-    name, it means that jenkins-job-builder can not call the variable
-    substitution on the contents of the file. This means that the
-    ``!include-raw:`` tag will behave as though ``!include-raw-escape:`` tag
-    was used instead whenever name substitution on the filename is to be
-    performed.
-
-    Given the behaviour described above, when substitution is to be performed
-    on any filename passed via ``!include-raw-escape:`` the tag will be
-    automatically converted to ``!include-raw:`` and no escaping will be
-    performed.
-
 
 The tag ``!include-jinja2:`` will treat the given string or list of strings as
 filenames to be opened as Jinja2 templates, which should be rendered to a

tests/yamlparser/job_fixtures/lazy-load-scripts/subst_vars_1.1.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+#
+# Version 1.1 of the subst vars script.
+
+echo branch={branch}

tests/yamlparser/job_fixtures/lazy-load-scripts/subst_vars_1.2.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+#
+# Version 1.2 of the subst vars script.
+
+echo branch={branch}

tests/yamlparser/job_fixtures/lazy-load-with-variables.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <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"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>#!/bin/bash
+#
+# Version 1.1 of the subst vars script.
+
+echo branch=master
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <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"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>#!/bin/bash
+#
+# Version 1.2 of the subst vars script.
+
+echo branch=feature
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>

tests/yamlparser/job_fixtures/lazy-load-with-variables.yaml

@@ -0,0 +1,18 @@
+# Variables should be substituted in included raw files
+# when their path themselves contains variables.
+
+- job-template:
+    name: 'sample-job-{version}'
+    builders:
+    - shell:
+        !include-raw: lazy-load-scripts/subst_vars_{version}.sh
+
+- project:
+    name: sample-project
+    branch: master
+    version:
+    - 1.1
+    - 1.2:
+        branch: feature
+    jobs:
+    - 'sample-job-{version}'