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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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