Implements: Archive publisher allow-empty setting.

The archive publisher did not allow setting the allowEmptyArchive setting in the YAML.
This change adds configuring the setting if it is defined in the YAML file. If the value
is 'true' then it is set, else it is 'false'. The default Jenkins behavior is 'false' disallowing
builds to pass without storing the archived data.

Updated the doc string to add that there is a default value (false) which is also the default Jenkins behavior.
Cleand up the value assignment, and typed it to a str().

fixed pep8 violation

Addresses patchset 3 request to update the doc string to use the test directly.
Would like to have more discussion around the second point in patchset 3 around having
the new code add a line of XML.

Change-Id: I5e0c9ed7e8ea669a8d0e8f267ebb02d5f0b6ae73

jenkins_jobs/modules/publishers.py

@@ -40,12 +40,13 @@ def archive(parser, xml_parent, data):
     :arg str excludes: path specifier for artifacts to exclude
     :arg bool latest-only: only keep the artifacts from the latest
       successful build
+    :arg bool allow-empty:  pass the build if no artifacts are
+      found (default false)
 
-    Example::
+    Example:
+
+    .. literalinclude::  /../../tests/publishers/fixtures/archive001.yaml
 
-      publishers:
-        - archive:
-            artifacts: '*.tar.gz'
     """
     logger = logging.getLogger("%s:archive" % __name__)
     archiver = XML.SubElement(xml_parent, 'hudson.tasks.ArtifactArchiver')
@@ -66,6 +67,11 @@ def archive(parser, xml_parent, data):
     else:
         latest.text = 'false'
 
+    if 'allow-empty' in data:
+        empty = XML.SubElement(archiver, 'allowEmptyArchive')
+        # Default behavior is to fail the build.
+        empty.text = str(data.get('allow-empty', False)).lower()
+
 
 def blame_upstream(parser, xml_parent, data):
     """yaml: blame-upstream

tests/publishers/fixtures/archive001.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" ?>
+<project>
+    <publishers>
+        <hudson.tasks.ArtifactArchiver>
+            <artifacts>*.tar.gz</artifacts>
+            <latestOnly>false</latestOnly>
+            <allowEmptyArchive>true</allowEmptyArchive>
+        </hudson.tasks.ArtifactArchiver>
+    </publishers>
+</project>

tests/publishers/fixtures/archive001.yaml

@@ -0,0 +1,4 @@
+publishers:
+  - archive:
+      artifacts: '*.tar.gz'
+      allow-empty: 'true'