Standardize docstrings for properties module

Move remaining examples to unit tests, remove unnecessary '\' and align docstrings to the predominate standard throughout the project. Fix broken authenticated-build highlighted by the added unit test. Change-Id: Ic9700f587073946be17be543920a4a3ed7cd19d0
2015-11-14 19:42:04 +00:00 · 2015-11-14 19:42:04 +00:00 · a796a593dc
commit a796a593dc
parent 15e06f9586
15 changed files with 201 additions and 105 deletions
--- a/jenkins_jobs/modules/properties.py
+++ b/jenkins_jobs/modules/properties.py
@ -45,13 +45,14 @@ def builds_chain_fingerprinter(parser, xml_parent, data):
    <Builds+chain+fingerprinter>`.

    :arg bool per-builds-chain: enable builds hierarchy fingerprinting
-        (default False)
+        (default false)
    :arg bool per-job-chain: enable jobs hierarchy fingerprinting
-        (default False)
+        (default false)

    Example:

    .. literalinclude:: /../../tests/properties/fixtures/fingerprinter.yaml
+       :language: yaml
    """
    fingerprinter = XML.SubElement(xml_parent,
                                   'org.jenkinsci.plugins.'
@ -75,11 +76,11 @@ def ownership(parser, xml_parent, data):
    Example:

    .. literalinclude:: /../../tests/properties/fixtures/ownership.yaml
+       :language: yaml
    """
-    ownership_plugin = \
-        XML.SubElement(xml_parent,
-                       'com.synopsys.arc.'
-                       'jenkins.plugins.ownership.jobs.JobOwnerJobProperty')
+    ownership_plugin = XML.SubElement(
+        xml_parent,
+        'com.synopsys.arc.jenkins.plugins.ownership.jobs.JobOwnerJobProperty')
    ownership = XML.SubElement(ownership_plugin, 'ownership')
    owner = str(data.get('enabled', True)).lower()
    XML.SubElement(ownership, 'ownershipEnabled').text = owner
@ -100,15 +101,12 @@ def promoted_build(parser, xml_parent, data):
    Requires the Jenkins :jenkins-wiki:`Promoted Builds Plugin
    <Promoted+Builds+Plugin>`.

-    :arg list names: the promoted build names
+    :arg list names: the promoted build names (optional)

-    Example::
+    Example:

-      properties:
-        - promoted-build:
-            names:
-              - "Release to QA"
-              - "Jane Must Approve"
+    .. literalinclude:: /../../tests/properties/fixtures/promoted_build.yaml
+       :language: yaml
    """
    promoted = XML.SubElement(xml_parent, 'hudson.plugins.promoted__builds.'
                                          'JobPropertyImpl')
@ -123,13 +121,12 @@ def github(parser, xml_parent, data):
    """yaml: github
    Sets the GitHub URL for the project.

-    :arg str url: the GitHub URL
+    :arg str url: the GitHub URL (required)

-    Example::
+    Example:

-      properties:
-        - github:
-            url: https://github.com/openstack-infra/jenkins-job-builder/
+    .. literalinclude:: /../../tests/properties/fixtures/github.yaml
+       :language: yaml
    """
    github = XML.SubElement(xml_parent,
                            'com.coravy.hudson.plugins.github.'
@ -143,11 +140,12 @@ def least_load(parser, xml_parent, data):
    Enables the Least Load Plugin.
    Requires the Jenkins :jenkins-wiki:`Least Load Plugin <Least+Load+Plugin>`.

-    :arg bool disabled: whether or not leastload is disabled (default True)
+    :arg bool disabled: whether or not leastload is disabled (default true)

    Example:

    .. literalinclude:: /../../tests/properties/fixtures/least-load002.yaml
+       :language: yaml
    """
    least = XML.SubElement(xml_parent,
                           'org.bstick12.jenkinsci.plugins.leastload.'
@ -165,19 +163,14 @@ def throttle(parser, xml_parent, data):

    :arg int max-per-node: max concurrent builds per node (default 0)
    :arg int max-total: max concurrent builds (default 0)
-    :arg bool enabled: whether throttling is enabled (default True)
+    :arg bool enabled: whether throttling is enabled (default true)
    :arg str option: throttle `project` or `category`
    :arg list categories: multiproject throttle categories

-    Example::
-
-      properties:
-        - throttle:
-            max-total: 4
-            categories:
-              - cat1
-              - cat2
+    Example:

+    .. literalinclude:: /../../tests/properties/fixtures/throttle001.yaml
+       :language: yaml
    """
    throttle = XML.SubElement(xml_parent,
                              'hudson.plugins.throttleconcurrents.'
@ -215,6 +208,7 @@ def sidebar(parser, xml_parent, data):
    Example:

    .. literalinclude:: /../../tests/properties/fixtures/sidebar02.yaml
+       :language: yaml
    """
    sidebar = xml_parent.find('hudson.plugins.sidebar__link.ProjectLinks')
    if sidebar is None:
@ -284,58 +278,49 @@ def authenticated_build(parser, xml_parent, data):
    Specifies an authorization matrix where only authenticated users
    may trigger a build.

-    DEPRECATED
+    .. deprecated:: 0.1.0. Please use :ref:`authorization <authorization>`.

-    Example::
+    Example:
+
+    .. literalinclude::
+        /../../tests/properties/fixtures/authenticated_build.yaml
+       :language: yaml

-      properties:
-        - authenticated-build
    """
    # TODO: generalize this
-    if data:
-        security = XML.SubElement(xml_parent,
-                                  'hudson.security.'
-                                  'AuthorizationMatrixProperty')
-        XML.SubElement(security, 'permission').text = \
-            'hudson.model.Item.Build:authenticated'
+    security = XML.SubElement(xml_parent,
+                              'hudson.security.'
+                              'AuthorizationMatrixProperty')
+    XML.SubElement(security, 'permission').text = (
+        'hudson.model.Item.Build:authenticated')


 def authorization(parser, xml_parent, data):
    """yaml: authorization
    Specifies an authorization matrix

-    The available rights are:
-      job-delete
-      job-configure
-      job-read
-      job-extended-read
-      job-discover
-      job-build
-      job-workspace
-      job-cancel
-      run-delete
-      run-update
-      scm-tag
+    :arg list <name>: `<name>` is the name of the group or user, containing
+        the list of rights to grant.

-    Example::
+       :<name> rights:
+            * **job-delete**
+            * **job-configure**
+            * **job-read**
+            * **job-extended-read**
+            * **job-discover**
+            * **job-build**
+            * **job-workspace**
+            * **job-cancel**
+            * **run-delete**
+            * **run-update**
+            * **scm-tag**
+
+    Example:
+
+    .. literalinclude::
+        /../../tests/properties/fixtures/authorization_matrix.yaml
+       :language: yaml

-      properties:
-        - authorization:
-            admin:
-              - job-delete
-              - job-configure
-              - job-read
-              - job-discover
-              - job-build
-              - job-workspace
-              - job-cancel
-              - run-delete
-              - run-update
-              - scm-tag
-            anonymous:
-              - job-discover
-              - job-read
-              - job-extended-read
    """

    mapping = {
@ -388,11 +373,10 @@ def priority_sorter(parser, xml_parent, data):
    :arg int priority: Priority of the job.  Higher value means higher
        priority, with 100 as the standard priority. (required)

-    Example::
+    Example:

-        properties:
-          - priority-sorter:
-              priority: 150
+    .. literalinclude:: /../../tests/properties/fixtures/priority_sorter.yaml
+       :language: yaml
    """
    priority_sorter_tag = XML.SubElement(xml_parent,
                                         'hudson.queueSorter.'
@ -410,22 +394,19 @@ def build_blocker(parser, xml_parent, data):
    Requires the Jenkins :jenkins-wiki:`Build Blocker Plugin
    <Build+Blocker+Plugin>`.

-    :arg bool use-build-blocker: Enable or disable build blocker
-        (default true)
-    :arg list blocking-jobs: One regular expression per line
-        to select blocking jobs by their names. (required)
-
+    :arg bool use-build-blocker: Enable or disable build blocker (default true)
+    :arg list blocking-jobs: One regular expression per line to select
+        blocking jobs by their names. (required)
    :arg str block-level: block build globally ('GLOBAL') or per node ('NODE')
        (default 'GLOBAL')
-
    :arg str queue-scanning: scan build queue for all builds ('ALL') or only
        buildable builds ('BUILDABLE') (default 'DISABLED'))

-
    Example:

-    .. literalinclude:: \
-            /../../tests/properties/fixtures/build-blocker01.yaml
+    .. literalinclude::
+        /../../tests/properties/fixtures/build-blocker01.yaml
+       :language: yaml
    """
    blocker = XML.SubElement(xml_parent,
                             'hudson.plugins.'
@ -466,14 +447,14 @@ def copyartifact(parser, xml_parent, data):
    Requires the Jenkins :jenkins-wiki:`Copy Artifact plugin
    <Copy+Artifact+Plugin>`.

-    :arg string projects: comma separated list of projects that can copy
+    :arg str projects: comma separated list of projects that can copy
        artifacts of this project. Wild card character '*' is available.

-
    Example:

-    .. literalinclude:: \
-            /../../tests/properties/fixtures/copyartifact.yaml
+    .. literalinclude::
+        /../../tests/properties/fixtures/copyartifact.yaml
+       :language: yaml

    """
    copyartifact = XML.SubElement(xml_parent,
@ -503,12 +484,14 @@ def batch_tasks(parser, xml_parent, data):

    :arg list batch-tasks: Batch tasks.

-        :Task: * **name** (`str`) Task name.
-               * **script** (`str`) Task script.
+        :Tasks:
+            * **name** (`str`) Task name.
+            * **script** (`str`) Task script.

    Example:

    .. literalinclude:: /../../tests/properties/fixtures/batch-task.yaml
+       :language: yaml

    """
    pdef = XML.SubElement(xml_parent,
@ -531,10 +514,10 @@ def heavy_job(parser, xml_parent, data):
    :arg int weight: Specify the total number of executors
        that this job should occupy (default 1)

-
    Example:

    .. literalinclude:: /../../tests/properties/fixtures/heavy-job.yaml
+       :language: yaml

    """
    heavyjob = XML.SubElement(xml_parent,
@ -553,15 +536,16 @@ def slave_utilization(parser, xml_parent, data):
    <Slave+Utilization+Plugin>`.

    :arg int slave-percentage: Specify the percentage of a slave's execution
-        slots that this job should occupy (default: 0)
+        slots that this job should occupy (default 0)
    :arg bool single-instance-per-slave: Control whether concurrent instances
        of this job will be permitted to run in parallel on a single slave
-        (default: False)
+        (default false)

    Example:

-    .. literalinclude:: \
-            /../../tests/properties/fixtures/slave-utilization1.yaml
+    .. literalinclude::
+        /../../tests/properties/fixtures/slave-utilization1.yaml
+       :language: yaml
    """
    utilization = XML.SubElement(
        xml_parent, 'com.suryagaddipati.jenkins.SlaveUtilizationProperty')
@ -579,15 +563,16 @@ def delivery_pipeline(parser, xml_parent, data):
    Requires the Jenkins :jenkins-wiki:`Delivery Pipeline Plugin
    <Delivery+Pipeline+Plugin>`.

+    :arg str stage: Name of the stage for this job (default '')
+    :arg str task: Name of the task for this job (default '')
    :arg str description: task description template for this job
-        (default: '')
-    :arg str stage: Name of the stage for this job (default: '')
-    :arg str task: Name of the task for this job (default: '')
+        (default '')

    Example:

-    .. literalinclude:: \
-            /../../tests/properties/fixtures/delivery-pipeline1.yaml
+    .. literalinclude::
+        /../../tests/properties/fixtures/delivery-pipeline1.yaml
+       :language: yaml

    """
    pipeline = XML.SubElement(xml_parent,
@ -609,8 +594,9 @@ def zeromq_event(parser, xml_parent, data):

    Example:

-    .. literalinclude:: \
-            /../../tests/properties/fixtures/zeromq-event.yaml
+    .. literalinclude::
+        /../../tests/properties/fixtures/zeromq-event.yaml
+       :language: yaml

    """

@ -626,14 +612,15 @@ def rebuild(parser, xml_parent, data):
    <Rebuild+Plugin>`.

    :arg bool auto-rebuild: Rebuild without asking for parameters
-        (default: False)
+        (default false)
    :arg bool rebuild-disabled: Disable rebuilding for this job
-        (default: False)
+        (default false)

    Example:

-    .. literalinclude:: \
-            /../../tests/properties/fixtures/rebuild.yaml
+    .. literalinclude::
+        /../../tests/properties/fixtures/rebuild.yaml
+       :language: yaml
    """
    sub_element = XML.SubElement(xml_parent,
                                 'com.sonyericsson.rebuild.RebuildSettings')
--- a/tests/properties/fixtures/authenticated_build.xml
+++ b/tests/properties/fixtures/authenticated_build.xml
@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <hudson.security.AuthorizationMatrixProperty>
+      <permission>hudson.model.Item.Build:authenticated</permission>
+    </hudson.security.AuthorizationMatrixProperty>
+  </properties>
+</project>
--- a/tests/properties/fixtures/authenticated_build.yaml
+++ b/tests/properties/fixtures/authenticated_build.yaml
@ -0,0 +1,2 @@
+properties:
+  - authenticated-build
--- a/tests/properties/fixtures/authorization_matrix.xml
+++ b/tests/properties/fixtures/authorization_matrix.xml
@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <hudson.security.AuthorizationMatrixProperty>
+      <permission>hudson.model.Item.Delete:admin</permission>
+      <permission>hudson.model.Item.Configure:admin</permission>
+      <permission>hudson.model.Item.Read:admin</permission>
+      <permission>hudson.model.Item.Discover:admin</permission>
+      <permission>hudson.model.Item.Build:admin</permission>
+      <permission>hudson.model.Item.Workspace:admin</permission>
+      <permission>hudson.model.Item.Cancel:admin</permission>
+      <permission>hudson.model.Run.Delete:admin</permission>
+      <permission>hudson.model.Run.Update:admin</permission>
+      <permission>hudson.scm.SCM.Tag:admin</permission>
+      <permission>hudson.model.Item.Discover:anonymous</permission>
+      <permission>hudson.model.Item.Read:anonymous</permission>
+      <permission>hudson.model.Item.ExtendedRead:anonymous</permission>
+    </hudson.security.AuthorizationMatrixProperty>
+  </properties>
+</project>
--- a/tests/properties/fixtures/authorization_matrix.yaml
+++ b/tests/properties/fixtures/authorization_matrix.yaml
@ -0,0 +1,17 @@
+properties:
+  - authorization:
+      admin:
+        - job-delete
+        - job-configure
+        - job-read
+        - job-discover
+        - job-build
+        - job-workspace
+        - job-cancel
+        - run-delete
+        - run-update
+        - scm-tag
+      anonymous:
+        - job-discover
+        - job-read
+        - job-extended-read
--- a/tests/properties/fixtures/github.xml
+++ b/tests/properties/fixtures/github.xml
@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <com.coravy.hudson.plugins.github.GithubProjectProperty>
+      <projectUrl>https://github.com/openstack-infra/jenkins-job-builder/</projectUrl>
+    </com.coravy.hudson.plugins.github.GithubProjectProperty>
+  </properties>
+</project>
--- a/tests/properties/fixtures/github.yaml
+++ b/tests/properties/fixtures/github.yaml
@ -0,0 +1,3 @@
+properties:
+  - github:
+      url: https://github.com/openstack-infra/jenkins-job-builder/
--- a/tests/properties/fixtures/priority_sorter.xml
+++ b/tests/properties/fixtures/priority_sorter.xml
@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <hudson.queueSorter.PrioritySorterJobProperty>
+      <priority>150</priority>
+    </hudson.queueSorter.PrioritySorterJobProperty>
+  </properties>
+</project>
--- a/tests/properties/fixtures/priority_sorter.yaml
+++ b/tests/properties/fixtures/priority_sorter.yaml
@ -0,0 +1,3 @@
+properties:
+  - priority-sorter:
+      priority: 150
--- a/tests/properties/fixtures/promoted_build.xml
+++ b/tests/properties/fixtures/promoted_build.xml
@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <hudson.plugins.promoted__builds.JobPropertyImpl>
+      <activeProcessNames>
+        <string>Release to QA</string>
+        <string>Jane Must Approve</string>
+      </activeProcessNames>
+    </hudson.plugins.promoted__builds.JobPropertyImpl>
+  </properties>
+</project>
--- a/tests/properties/fixtures/promoted_build.yaml
+++ b/tests/properties/fixtures/promoted_build.yaml
@ -0,0 +1,5 @@
+properties:
+  - promoted-build:
+      names:
+        - "Release to QA"
+        - "Jane Must Approve"
--- a/tests/properties/fixtures/throttle001.xml
+++ b/tests/properties/fixtures/throttle001.xml
@ -2,14 +2,14 @@
 <project>
  <properties>
    <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
-      <maxConcurrentPerNode>0</maxConcurrentPerNode>
+      <maxConcurrentPerNode>2</maxConcurrentPerNode>
      <maxConcurrentTotal>4</maxConcurrentTotal>
      <throttleEnabled>true</throttleEnabled>
      <categories>
        <string>cat1</string>
        <string>cat2</string>
      </categories>
-      <throttleOption/>
+      <throttleOption>category</throttleOption>
      <configVersion>1</configVersion>
    </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
  </properties>
--- a/tests/properties/fixtures/throttle001.yaml
+++ b/tests/properties/fixtures/throttle001.yaml
@ -1,6 +1,8 @@
 properties:
  - throttle:
+      max-per-node: 2
      max-total: 4
      categories:
        - cat1
        - cat2
+      option: category
--- a/tests/properties/fixtures/throttle002.xml
+++ b/tests/properties/fixtures/throttle002.xml
@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
+      <maxConcurrentPerNode>0</maxConcurrentPerNode>
+      <maxConcurrentTotal>0</maxConcurrentTotal>
+      <throttleEnabled>true</throttleEnabled>
+      <categories>
+        <string>cat1</string>
+        <string>cat2</string>
+      </categories>
+      <throttleOption>project</throttleOption>
+      <configVersion>1</configVersion>
+    </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
+  </properties>
+</project>
--- a/tests/properties/fixtures/throttle002.yaml
+++ b/tests/properties/fixtures/throttle002.yaml
@ -0,0 +1,6 @@
+properties:
+  - throttle:
+      categories:
+        - cat1
+        - cat2
+      option: project