Add documentation and example on the usage of yaml anchors and aliases.

Change-Id: I9227820cfdccace2d8a463529da64041c156e8ec

doc/source/definition.rst

@@ -306,10 +306,10 @@ You can define variables that will be realized in a `Job Template`.
 
 Would create jobs ``build-i386`` and ``build-amd64``.
 
-.. _advanced:
+.. _variable_references:
 
-Advanced
-^^^^^^^^
+Variable References
+^^^^^^^^^^^^^^^^^^^
 
 If you want to pass an object (boolean, list or dict) to templates you can
 use an ``{obj:key}`` variable in the job template.  This triggers the use
@@ -320,6 +320,15 @@ For example:
 .. literalinclude::  /../../tests/yamlparser/fixtures/custom_distri.yaml
 
 
+The yaml specification supports `anchors and aliases`__ which means
+that JJB definitions allow references to variables in templates.
+
+__ http://yaml.org/spec/1.2/spec.html#id2765878
+
+For example:
+
+.. literalinclude::  /../../tests/yamlparser/fixtures/yaml_anchor.yaml
+
 Custom Yaml Tags
 ----------------
 

tests/yamlparser/fixtures/yaml_anchor.xml

@@ -0,0 +1,25 @@
+<?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/>
+  <publishers/>
+  <buildWrappers>
+    <hudson.plugins.build__timeout.BuildTimeoutWrapper>
+      <timeoutMinutes>180</timeoutMinutes>
+      <failBuild>true</failBuild>
+      <writingDescription>false</writingDescription>
+      <timeoutPercentage>0</timeoutPercentage>
+      <timeoutMinutesElasticDefault>3</timeoutMinutesElasticDefault>
+      <timeoutType>absolute</timeoutType>
+    </hudson.plugins.build__timeout.BuildTimeoutWrapper>
+    <hudson.plugins.timestamper.TimestamperBuildWrapper/>
+  </buildWrappers>
+</project>

tests/yamlparser/fixtures/yaml_anchor.yaml

@@ -0,0 +1,20 @@
+- wrapper_defaults: &wrapper_defaults
+    name: 'wrapper_defaults'
+    wrappers:
+      - timeout:
+          timeout: 180
+          fail: true
+      - timestamps
+
+- job_defaults: &job_defaults
+    name: 'defaults'
+    <<: *wrapper_defaults
+
+- job-template:
+    name: 'myjob'
+    <<: *job_defaults
+
+- project:
+    name: myproject
+    jobs:
+      - myjob