Add additional documentation for passing objects to templates

I noticed that users were not really aware of how this feature
worked so added additional documentation for it.

Change-Id: Ic5385ae859295cdd015d698ede3da4988efd9ca7
Closes-Bug: 1335945

doc/source/definition.rst

@@ -311,7 +311,9 @@ Would create jobs ``build-i386`` and ``build-amd64``.
 Advanced
 ^^^^^^^^
 
-If you want to use lists or dicts variables you can use ``{obj:key}``.
+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
+of code that retains the original object type.
 
 For example:
 

tests/yamlparser/fixtures/custom_distri.xml

@@ -23,6 +23,7 @@
   <actions/>
   <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
   <keepDependencies>false</keepDependencies>
+  <disabled>true</disabled>
   <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
   <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
   <concurrentBuild>false</concurrentBuild>

tests/yamlparser/fixtures/custom_distri.yaml

@@ -1,5 +1,6 @@
 - project:
     name: test_custom_distri
+    disabled: true
     distributions: !!python/tuple [precise, jessie]
     architectures: !!python/tuple &architectures
       - amd64
@@ -14,6 +15,7 @@
 - job-template:
       name: '{name}-source'
       project-type: matrix
+      disabled: '{obj:disabled}'
       axes:
         - axis:
             type: user-defined