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
This commit is contained in:
Darragh Bailey 2015-11-14 19:42:04 +00:00
parent 15e06f9586
commit a796a593dc
15 changed files with 201 additions and 105 deletions

@ -45,13 +45,14 @@ def builds_chain_fingerprinter(parser, xml_parent, data):
<Builds+chain+fingerprinter>`. <Builds+chain+fingerprinter>`.
:arg bool per-builds-chain: enable builds hierarchy fingerprinting :arg bool per-builds-chain: enable builds hierarchy fingerprinting
(default False) (default false)
:arg bool per-job-chain: enable jobs hierarchy fingerprinting :arg bool per-job-chain: enable jobs hierarchy fingerprinting
(default False) (default false)
Example: Example:
.. literalinclude:: /../../tests/properties/fixtures/fingerprinter.yaml .. literalinclude:: /../../tests/properties/fixtures/fingerprinter.yaml
:language: yaml
""" """
fingerprinter = XML.SubElement(xml_parent, fingerprinter = XML.SubElement(xml_parent,
'org.jenkinsci.plugins.' 'org.jenkinsci.plugins.'
@ -75,11 +76,11 @@ def ownership(parser, xml_parent, data):
Example: Example:
.. literalinclude:: /../../tests/properties/fixtures/ownership.yaml .. literalinclude:: /../../tests/properties/fixtures/ownership.yaml
:language: yaml
""" """
ownership_plugin = \ ownership_plugin = XML.SubElement(
XML.SubElement(xml_parent, xml_parent,
'com.synopsys.arc.' 'com.synopsys.arc.jenkins.plugins.ownership.jobs.JobOwnerJobProperty')
'jenkins.plugins.ownership.jobs.JobOwnerJobProperty')
ownership = XML.SubElement(ownership_plugin, 'ownership') ownership = XML.SubElement(ownership_plugin, 'ownership')
owner = str(data.get('enabled', True)).lower() owner = str(data.get('enabled', True)).lower()
XML.SubElement(ownership, 'ownershipEnabled').text = owner 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 Requires the Jenkins :jenkins-wiki:`Promoted Builds Plugin
<Promoted+Builds+Plugin>`. <Promoted+Builds+Plugin>`.
:arg list names: the promoted build names :arg list names: the promoted build names (optional)
Example:: Example:
properties: .. literalinclude:: /../../tests/properties/fixtures/promoted_build.yaml
- promoted-build: :language: yaml
names:
- "Release to QA"
- "Jane Must Approve"
""" """
promoted = XML.SubElement(xml_parent, 'hudson.plugins.promoted__builds.' promoted = XML.SubElement(xml_parent, 'hudson.plugins.promoted__builds.'
'JobPropertyImpl') 'JobPropertyImpl')
@ -123,13 +121,12 @@ def github(parser, xml_parent, data):
"""yaml: github """yaml: github
Sets the GitHub URL for the project. Sets the GitHub URL for the project.
:arg str url: the GitHub URL :arg str url: the GitHub URL (required)
Example:: Example:
properties: .. literalinclude:: /../../tests/properties/fixtures/github.yaml
- github: :language: yaml
url: https://github.com/openstack-infra/jenkins-job-builder/
""" """
github = XML.SubElement(xml_parent, github = XML.SubElement(xml_parent,
'com.coravy.hudson.plugins.github.' 'com.coravy.hudson.plugins.github.'
@ -143,11 +140,12 @@ def least_load(parser, xml_parent, data):
Enables the Least Load Plugin. Enables the Least Load Plugin.
Requires the Jenkins :jenkins-wiki:`Least Load Plugin <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: Example:
.. literalinclude:: /../../tests/properties/fixtures/least-load002.yaml .. literalinclude:: /../../tests/properties/fixtures/least-load002.yaml
:language: yaml
""" """
least = XML.SubElement(xml_parent, least = XML.SubElement(xml_parent,
'org.bstick12.jenkinsci.plugins.leastload.' '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-per-node: max concurrent builds per node (default 0)
:arg int max-total: max concurrent builds (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 str option: throttle `project` or `category`
:arg list categories: multiproject throttle categories :arg list categories: multiproject throttle categories
Example:: Example:
properties:
- throttle:
max-total: 4
categories:
- cat1
- cat2
.. literalinclude:: /../../tests/properties/fixtures/throttle001.yaml
:language: yaml
""" """
throttle = XML.SubElement(xml_parent, throttle = XML.SubElement(xml_parent,
'hudson.plugins.throttleconcurrents.' 'hudson.plugins.throttleconcurrents.'
@ -215,6 +208,7 @@ def sidebar(parser, xml_parent, data):
Example: Example:
.. literalinclude:: /../../tests/properties/fixtures/sidebar02.yaml .. literalinclude:: /../../tests/properties/fixtures/sidebar02.yaml
:language: yaml
""" """
sidebar = xml_parent.find('hudson.plugins.sidebar__link.ProjectLinks') sidebar = xml_parent.find('hudson.plugins.sidebar__link.ProjectLinks')
if sidebar is None: if sidebar is None:
@ -284,58 +278,49 @@ def authenticated_build(parser, xml_parent, data):
Specifies an authorization matrix where only authenticated users Specifies an authorization matrix where only authenticated users
may trigger a build. 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 # TODO: generalize this
if data: security = XML.SubElement(xml_parent,
security = XML.SubElement(xml_parent, 'hudson.security.'
'hudson.security.' 'AuthorizationMatrixProperty')
'AuthorizationMatrixProperty') XML.SubElement(security, 'permission').text = (
XML.SubElement(security, 'permission').text = \ 'hudson.model.Item.Build:authenticated')
'hudson.model.Item.Build:authenticated'
def authorization(parser, xml_parent, data): def authorization(parser, xml_parent, data):
"""yaml: authorization """yaml: authorization
Specifies an authorization matrix Specifies an authorization matrix
The available rights are: :arg list <name>: `<name>` is the name of the group or user, containing
job-delete the list of rights to grant.
job-configure
job-read
job-extended-read
job-discover
job-build
job-workspace
job-cancel
run-delete
run-update
scm-tag
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 = { mapping = {
@ -388,11 +373,10 @@ def priority_sorter(parser, xml_parent, data):
:arg int priority: Priority of the job. Higher value means higher :arg int priority: Priority of the job. Higher value means higher
priority, with 100 as the standard priority. (required) priority, with 100 as the standard priority. (required)
Example:: Example:
properties: .. literalinclude:: /../../tests/properties/fixtures/priority_sorter.yaml
- priority-sorter: :language: yaml
priority: 150
""" """
priority_sorter_tag = XML.SubElement(xml_parent, priority_sorter_tag = XML.SubElement(xml_parent,
'hudson.queueSorter.' 'hudson.queueSorter.'
@ -410,22 +394,19 @@ def build_blocker(parser, xml_parent, data):
Requires the Jenkins :jenkins-wiki:`Build Blocker Plugin Requires the Jenkins :jenkins-wiki:`Build Blocker Plugin
<Build+Blocker+Plugin>`. <Build+Blocker+Plugin>`.
:arg bool use-build-blocker: Enable or disable build blocker :arg bool use-build-blocker: Enable or disable build blocker (default true)
(default true) :arg list blocking-jobs: One regular expression per line to select
:arg list blocking-jobs: One regular expression per line blocking jobs by their names. (required)
to select blocking jobs by their names. (required)
:arg str block-level: block build globally ('GLOBAL') or per node ('NODE') :arg str block-level: block build globally ('GLOBAL') or per node ('NODE')
(default 'GLOBAL') (default 'GLOBAL')
:arg str queue-scanning: scan build queue for all builds ('ALL') or only :arg str queue-scanning: scan build queue for all builds ('ALL') or only
buildable builds ('BUILDABLE') (default 'DISABLED')) buildable builds ('BUILDABLE') (default 'DISABLED'))
Example: Example:
.. literalinclude:: \ .. literalinclude::
/../../tests/properties/fixtures/build-blocker01.yaml /../../tests/properties/fixtures/build-blocker01.yaml
:language: yaml
""" """
blocker = XML.SubElement(xml_parent, blocker = XML.SubElement(xml_parent,
'hudson.plugins.' 'hudson.plugins.'
@ -466,14 +447,14 @@ def copyartifact(parser, xml_parent, data):
Requires the Jenkins :jenkins-wiki:`Copy Artifact plugin Requires the Jenkins :jenkins-wiki:`Copy Artifact plugin
<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. artifacts of this project. Wild card character '*' is available.
Example: Example:
.. literalinclude:: \ .. literalinclude::
/../../tests/properties/fixtures/copyartifact.yaml /../../tests/properties/fixtures/copyartifact.yaml
:language: yaml
""" """
copyartifact = XML.SubElement(xml_parent, copyartifact = XML.SubElement(xml_parent,
@ -503,12 +484,14 @@ def batch_tasks(parser, xml_parent, data):
:arg list batch-tasks: Batch tasks. :arg list batch-tasks: Batch tasks.
:Task: * **name** (`str`) Task name. :Tasks:
* **script** (`str`) Task script. * **name** (`str`) Task name.
* **script** (`str`) Task script.
Example: Example:
.. literalinclude:: /../../tests/properties/fixtures/batch-task.yaml .. literalinclude:: /../../tests/properties/fixtures/batch-task.yaml
:language: yaml
""" """
pdef = XML.SubElement(xml_parent, 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 :arg int weight: Specify the total number of executors
that this job should occupy (default 1) that this job should occupy (default 1)
Example: Example:
.. literalinclude:: /../../tests/properties/fixtures/heavy-job.yaml .. literalinclude:: /../../tests/properties/fixtures/heavy-job.yaml
:language: yaml
""" """
heavyjob = XML.SubElement(xml_parent, heavyjob = XML.SubElement(xml_parent,
@ -553,15 +536,16 @@ def slave_utilization(parser, xml_parent, data):
<Slave+Utilization+Plugin>`. <Slave+Utilization+Plugin>`.
:arg int slave-percentage: Specify the percentage of a slave's execution :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 :arg bool single-instance-per-slave: Control whether concurrent instances
of this job will be permitted to run in parallel on a single slave of this job will be permitted to run in parallel on a single slave
(default: False) (default false)
Example: Example:
.. literalinclude:: \ .. literalinclude::
/../../tests/properties/fixtures/slave-utilization1.yaml /../../tests/properties/fixtures/slave-utilization1.yaml
:language: yaml
""" """
utilization = XML.SubElement( utilization = XML.SubElement(
xml_parent, 'com.suryagaddipati.jenkins.SlaveUtilizationProperty') 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 Requires the Jenkins :jenkins-wiki:`Delivery Pipeline Plugin
<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 :arg str description: task description template for this job
(default: '') (default '')
:arg str stage: Name of the stage for this job (default: '')
:arg str task: Name of the task for this job (default: '')
Example: Example:
.. literalinclude:: \ .. literalinclude::
/../../tests/properties/fixtures/delivery-pipeline1.yaml /../../tests/properties/fixtures/delivery-pipeline1.yaml
:language: yaml
""" """
pipeline = XML.SubElement(xml_parent, pipeline = XML.SubElement(xml_parent,
@ -609,8 +594,9 @@ def zeromq_event(parser, xml_parent, data):
Example: Example:
.. literalinclude:: \ .. literalinclude::
/../../tests/properties/fixtures/zeromq-event.yaml /../../tests/properties/fixtures/zeromq-event.yaml
:language: yaml
""" """
@ -626,14 +612,15 @@ def rebuild(parser, xml_parent, data):
<Rebuild+Plugin>`. <Rebuild+Plugin>`.
:arg bool auto-rebuild: Rebuild without asking for parameters :arg bool auto-rebuild: Rebuild without asking for parameters
(default: False) (default false)
:arg bool rebuild-disabled: Disable rebuilding for this job :arg bool rebuild-disabled: Disable rebuilding for this job
(default: False) (default false)
Example: Example:
.. literalinclude:: \ .. literalinclude::
/../../tests/properties/fixtures/rebuild.yaml /../../tests/properties/fixtures/rebuild.yaml
:language: yaml
""" """
sub_element = XML.SubElement(xml_parent, sub_element = XML.SubElement(xml_parent,
'com.sonyericsson.rebuild.RebuildSettings') 'com.sonyericsson.rebuild.RebuildSettings')

@ -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>

@ -0,0 +1,2 @@
properties:
- authenticated-build

@ -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>

@ -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

@ -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>

@ -0,0 +1,3 @@
properties:
- github:
url: https://github.com/openstack-infra/jenkins-job-builder/

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<project>
<properties>
<hudson.queueSorter.PrioritySorterJobProperty>
<priority>150</priority>
</hudson.queueSorter.PrioritySorterJobProperty>
</properties>
</project>

@ -0,0 +1,3 @@
properties:
- priority-sorter:
priority: 150

@ -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>

@ -0,0 +1,5 @@
properties:
- promoted-build:
names:
- "Release to QA"
- "Jane Must Approve"

@ -2,14 +2,14 @@
<project> <project>
<properties> <properties>
<hudson.plugins.throttleconcurrents.ThrottleJobProperty> <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
<maxConcurrentPerNode>0</maxConcurrentPerNode> <maxConcurrentPerNode>2</maxConcurrentPerNode>
<maxConcurrentTotal>4</maxConcurrentTotal> <maxConcurrentTotal>4</maxConcurrentTotal>
<throttleEnabled>true</throttleEnabled> <throttleEnabled>true</throttleEnabled>
<categories> <categories>
<string>cat1</string> <string>cat1</string>
<string>cat2</string> <string>cat2</string>
</categories> </categories>
<throttleOption/> <throttleOption>category</throttleOption>
<configVersion>1</configVersion> <configVersion>1</configVersion>
</hudson.plugins.throttleconcurrents.ThrottleJobProperty> </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
</properties> </properties>

@ -1,6 +1,8 @@
properties: properties:
- throttle: - throttle:
max-per-node: 2
max-total: 4 max-total: 4
categories: categories:
- cat1 - cat1
- cat2 - cat2
option: category

@ -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>

@ -0,0 +1,6 @@
properties:
- throttle:
categories:
- cat1
- cat2
option: project