Browse Source

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
tags/1.5.0
Darragh Bailey 3 years ago
parent
commit
a796a593dc

+ 92
- 105
jenkins_jobs/modules/properties.py View File

@@ -45,13 +45,14 @@ def builds_chain_fingerprinter(parser, xml_parent, data):
45 45
     <Builds+chain+fingerprinter>`.
46 46
 
47 47
     :arg bool per-builds-chain: enable builds hierarchy fingerprinting
48
-        (default False)
48
+        (default false)
49 49
     :arg bool per-job-chain: enable jobs hierarchy fingerprinting
50
-        (default False)
50
+        (default false)
51 51
 
52 52
     Example:
53 53
 
54 54
     .. literalinclude:: /../../tests/properties/fixtures/fingerprinter.yaml
55
+       :language: yaml
55 56
     """
56 57
     fingerprinter = XML.SubElement(xml_parent,
57 58
                                    'org.jenkinsci.plugins.'
@@ -75,11 +76,11 @@ def ownership(parser, xml_parent, data):
75 76
     Example:
76 77
 
77 78
     .. literalinclude:: /../../tests/properties/fixtures/ownership.yaml
79
+       :language: yaml
78 80
     """
79
-    ownership_plugin = \
80
-        XML.SubElement(xml_parent,
81
-                       'com.synopsys.arc.'
82
-                       'jenkins.plugins.ownership.jobs.JobOwnerJobProperty')
81
+    ownership_plugin = XML.SubElement(
82
+        xml_parent,
83
+        'com.synopsys.arc.jenkins.plugins.ownership.jobs.JobOwnerJobProperty')
83 84
     ownership = XML.SubElement(ownership_plugin, 'ownership')
84 85
     owner = str(data.get('enabled', True)).lower()
85 86
     XML.SubElement(ownership, 'ownershipEnabled').text = owner
@@ -100,15 +101,12 @@ def promoted_build(parser, xml_parent, data):
100 101
     Requires the Jenkins :jenkins-wiki:`Promoted Builds Plugin
101 102
     <Promoted+Builds+Plugin>`.
102 103
 
103
-    :arg list names: the promoted build names
104
+    :arg list names: the promoted build names (optional)
104 105
 
105
-    Example::
106
+    Example:
106 107
 
107
-      properties:
108
-        - promoted-build:
109
-            names:
110
-              - "Release to QA"
111
-              - "Jane Must Approve"
108
+    .. literalinclude:: /../../tests/properties/fixtures/promoted_build.yaml
109
+       :language: yaml
112 110
     """
113 111
     promoted = XML.SubElement(xml_parent, 'hudson.plugins.promoted__builds.'
114 112
                                           'JobPropertyImpl')
@@ -123,13 +121,12 @@ def github(parser, xml_parent, data):
123 121
     """yaml: github
124 122
     Sets the GitHub URL for the project.
125 123
 
126
-    :arg str url: the GitHub URL
124
+    :arg str url: the GitHub URL (required)
127 125
 
128
-    Example::
126
+    Example:
129 127
 
130
-      properties:
131
-        - github:
132
-            url: https://github.com/openstack-infra/jenkins-job-builder/
128
+    .. literalinclude:: /../../tests/properties/fixtures/github.yaml
129
+       :language: yaml
133 130
     """
134 131
     github = XML.SubElement(xml_parent,
135 132
                             'com.coravy.hudson.plugins.github.'
@@ -143,11 +140,12 @@ def least_load(parser, xml_parent, data):
143 140
     Enables the Least Load Plugin.
144 141
     Requires the Jenkins :jenkins-wiki:`Least Load Plugin <Least+Load+Plugin>`.
145 142
 
146
-    :arg bool disabled: whether or not leastload is disabled (default True)
143
+    :arg bool disabled: whether or not leastload is disabled (default true)
147 144
 
148 145
     Example:
149 146
 
150 147
     .. literalinclude:: /../../tests/properties/fixtures/least-load002.yaml
148
+       :language: yaml
151 149
     """
152 150
     least = XML.SubElement(xml_parent,
153 151
                            'org.bstick12.jenkinsci.plugins.leastload.'
@@ -165,19 +163,14 @@ def throttle(parser, xml_parent, data):
165 163
 
166 164
     :arg int max-per-node: max concurrent builds per node (default 0)
167 165
     :arg int max-total: max concurrent builds (default 0)
168
-    :arg bool enabled: whether throttling is enabled (default True)
166
+    :arg bool enabled: whether throttling is enabled (default true)
169 167
     :arg str option: throttle `project` or `category`
170 168
     :arg list categories: multiproject throttle categories
171 169
 
172
-    Example::
173
-
174
-      properties:
175
-        - throttle:
176
-            max-total: 4
177
-            categories:
178
-              - cat1
179
-              - cat2
170
+    Example:
180 171
 
172
+    .. literalinclude:: /../../tests/properties/fixtures/throttle001.yaml
173
+       :language: yaml
181 174
     """
182 175
     throttle = XML.SubElement(xml_parent,
183 176
                               'hudson.plugins.throttleconcurrents.'
@@ -215,6 +208,7 @@ def sidebar(parser, xml_parent, data):
215 208
     Example:
216 209
 
217 210
     .. literalinclude:: /../../tests/properties/fixtures/sidebar02.yaml
211
+       :language: yaml
218 212
     """
219 213
     sidebar = xml_parent.find('hudson.plugins.sidebar__link.ProjectLinks')
220 214
     if sidebar is None:
@@ -284,58 +278,49 @@ def authenticated_build(parser, xml_parent, data):
284 278
     Specifies an authorization matrix where only authenticated users
285 279
     may trigger a build.
286 280
 
287
-    DEPRECATED
281
+    .. deprecated:: 0.1.0. Please use :ref:`authorization <authorization>`.
282
+
283
+    Example:
288 284
 
289
-    Example::
285
+    .. literalinclude::
286
+        /../../tests/properties/fixtures/authenticated_build.yaml
287
+       :language: yaml
290 288
 
291
-      properties:
292
-        - authenticated-build
293 289
     """
294 290
     # TODO: generalize this
295
-    if data:
296
-        security = XML.SubElement(xml_parent,
297
-                                  'hudson.security.'
298
-                                  'AuthorizationMatrixProperty')
299
-        XML.SubElement(security, 'permission').text = \
300
-            'hudson.model.Item.Build:authenticated'
291
+    security = XML.SubElement(xml_parent,
292
+                              'hudson.security.'
293
+                              'AuthorizationMatrixProperty')
294
+    XML.SubElement(security, 'permission').text = (
295
+        'hudson.model.Item.Build:authenticated')
301 296
 
302 297
 
303 298
 def authorization(parser, xml_parent, data):
304 299
     """yaml: authorization
305 300
     Specifies an authorization matrix
306 301
 
307
-    The available rights are:
308
-      job-delete
309
-      job-configure
310
-      job-read
311
-      job-extended-read
312
-      job-discover
313
-      job-build
314
-      job-workspace
315
-      job-cancel
316
-      run-delete
317
-      run-update
318
-      scm-tag
319
-
320
-    Example::
321
-
322
-      properties:
323
-        - authorization:
324
-            admin:
325
-              - job-delete
326
-              - job-configure
327
-              - job-read
328
-              - job-discover
329
-              - job-build
330
-              - job-workspace
331
-              - job-cancel
332
-              - run-delete
333
-              - run-update
334
-              - scm-tag
335
-            anonymous:
336
-              - job-discover
337
-              - job-read
338
-              - job-extended-read
302
+    :arg list <name>: `<name>` is the name of the group or user, containing
303
+        the list of rights to grant.
304
+
305
+       :<name> rights:
306
+            * **job-delete**
307
+            * **job-configure**
308
+            * **job-read**
309
+            * **job-extended-read**
310
+            * **job-discover**
311
+            * **job-build**
312
+            * **job-workspace**
313
+            * **job-cancel**
314
+            * **run-delete**
315
+            * **run-update**
316
+            * **scm-tag**
317
+
318
+    Example:
319
+
320
+    .. literalinclude::
321
+        /../../tests/properties/fixtures/authorization_matrix.yaml
322
+       :language: yaml
323
+
339 324
     """
340 325
 
341 326
     mapping = {
@@ -388,11 +373,10 @@ def priority_sorter(parser, xml_parent, data):
388 373
     :arg int priority: Priority of the job.  Higher value means higher
389 374
         priority, with 100 as the standard priority. (required)
390 375
 
391
-    Example::
376
+    Example:
392 377
 
393
-        properties:
394
-          - priority-sorter:
395
-              priority: 150
378
+    .. literalinclude:: /../../tests/properties/fixtures/priority_sorter.yaml
379
+       :language: yaml
396 380
     """
397 381
     priority_sorter_tag = XML.SubElement(xml_parent,
398 382
                                          'hudson.queueSorter.'
@@ -410,22 +394,19 @@ def build_blocker(parser, xml_parent, data):
410 394
     Requires the Jenkins :jenkins-wiki:`Build Blocker Plugin
411 395
     <Build+Blocker+Plugin>`.
412 396
 
413
-    :arg bool use-build-blocker: Enable or disable build blocker
414
-        (default true)
415
-    :arg list blocking-jobs: One regular expression per line
416
-        to select blocking jobs by their names. (required)
417
-
397
+    :arg bool use-build-blocker: Enable or disable build blocker (default true)
398
+    :arg list blocking-jobs: One regular expression per line to select
399
+        blocking jobs by their names. (required)
418 400
     :arg str block-level: block build globally ('GLOBAL') or per node ('NODE')
419 401
         (default 'GLOBAL')
420
-
421 402
     :arg str queue-scanning: scan build queue for all builds ('ALL') or only
422 403
         buildable builds ('BUILDABLE') (default 'DISABLED'))
423 404
 
424
-
425 405
     Example:
426 406
 
427
-    .. literalinclude:: \
428
-            /../../tests/properties/fixtures/build-blocker01.yaml
407
+    .. literalinclude::
408
+        /../../tests/properties/fixtures/build-blocker01.yaml
409
+       :language: yaml
429 410
     """
430 411
     blocker = XML.SubElement(xml_parent,
431 412
                              'hudson.plugins.'
@@ -466,14 +447,14 @@ def copyartifact(parser, xml_parent, data):
466 447
     Requires the Jenkins :jenkins-wiki:`Copy Artifact plugin
467 448
     <Copy+Artifact+Plugin>`.
468 449
 
469
-    :arg string projects: comma separated list of projects that can copy
450
+    :arg str projects: comma separated list of projects that can copy
470 451
         artifacts of this project. Wild card character '*' is available.
471 452
 
472
-
473 453
     Example:
474 454
 
475
-    .. literalinclude:: \
476
-            /../../tests/properties/fixtures/copyartifact.yaml
455
+    .. literalinclude::
456
+        /../../tests/properties/fixtures/copyartifact.yaml
457
+       :language: yaml
477 458
 
478 459
     """
479 460
     copyartifact = XML.SubElement(xml_parent,
@@ -503,12 +484,14 @@ def batch_tasks(parser, xml_parent, data):
503 484
 
504 485
     :arg list batch-tasks: Batch tasks.
505 486
 
506
-        :Task: * **name** (`str`) Task name.
507
-               * **script** (`str`) Task script.
487
+        :Tasks:
488
+            * **name** (`str`) Task name.
489
+            * **script** (`str`) Task script.
508 490
 
509 491
     Example:
510 492
 
511 493
     .. literalinclude:: /../../tests/properties/fixtures/batch-task.yaml
494
+       :language: yaml
512 495
 
513 496
     """
514 497
     pdef = XML.SubElement(xml_parent,
@@ -531,10 +514,10 @@ def heavy_job(parser, xml_parent, data):
531 514
     :arg int weight: Specify the total number of executors
532 515
         that this job should occupy (default 1)
533 516
 
534
-
535 517
     Example:
536 518
 
537 519
     .. literalinclude:: /../../tests/properties/fixtures/heavy-job.yaml
520
+       :language: yaml
538 521
 
539 522
     """
540 523
     heavyjob = XML.SubElement(xml_parent,
@@ -553,15 +536,16 @@ def slave_utilization(parser, xml_parent, data):
553 536
     <Slave+Utilization+Plugin>`.
554 537
 
555 538
     :arg int slave-percentage: Specify the percentage of a slave's execution
556
-        slots that this job should occupy (default: 0)
539
+        slots that this job should occupy (default 0)
557 540
     :arg bool single-instance-per-slave: Control whether concurrent instances
558 541
         of this job will be permitted to run in parallel on a single slave
559
-        (default: False)
542
+        (default false)
560 543
 
561 544
     Example:
562 545
 
563
-    .. literalinclude:: \
564
-            /../../tests/properties/fixtures/slave-utilization1.yaml
546
+    .. literalinclude::
547
+        /../../tests/properties/fixtures/slave-utilization1.yaml
548
+       :language: yaml
565 549
     """
566 550
     utilization = XML.SubElement(
567 551
         xml_parent, 'com.suryagaddipati.jenkins.SlaveUtilizationProperty')
@@ -579,15 +563,16 @@ def delivery_pipeline(parser, xml_parent, data):
579 563
     Requires the Jenkins :jenkins-wiki:`Delivery Pipeline Plugin
580 564
     <Delivery+Pipeline+Plugin>`.
581 565
 
566
+    :arg str stage: Name of the stage for this job (default '')
567
+    :arg str task: Name of the task for this job (default '')
582 568
     :arg str description: task description template for this job
583
-        (default: '')
584
-    :arg str stage: Name of the stage for this job (default: '')
585
-    :arg str task: Name of the task for this job (default: '')
569
+        (default '')
586 570
 
587 571
     Example:
588 572
 
589
-    .. literalinclude:: \
590
-            /../../tests/properties/fixtures/delivery-pipeline1.yaml
573
+    .. literalinclude::
574
+        /../../tests/properties/fixtures/delivery-pipeline1.yaml
575
+       :language: yaml
591 576
 
592 577
     """
593 578
     pipeline = XML.SubElement(xml_parent,
@@ -609,8 +594,9 @@ def zeromq_event(parser, xml_parent, data):
609 594
 
610 595
     Example:
611 596
 
612
-    .. literalinclude:: \
613
-            /../../tests/properties/fixtures/zeromq-event.yaml
597
+    .. literalinclude::
598
+        /../../tests/properties/fixtures/zeromq-event.yaml
599
+       :language: yaml
614 600
 
615 601
     """
616 602
 
@@ -626,14 +612,15 @@ def rebuild(parser, xml_parent, data):
626 612
     <Rebuild+Plugin>`.
627 613
 
628 614
     :arg bool auto-rebuild: Rebuild without asking for parameters
629
-        (default: False)
615
+        (default false)
630 616
     :arg bool rebuild-disabled: Disable rebuilding for this job
631
-        (default: False)
617
+        (default false)
632 618
 
633 619
     Example:
634 620
 
635
-    .. literalinclude:: \
636
-            /../../tests/properties/fixtures/rebuild.yaml
621
+    .. literalinclude::
622
+        /../../tests/properties/fixtures/rebuild.yaml
623
+       :language: yaml
637 624
     """
638 625
     sub_element = XML.SubElement(xml_parent,
639 626
                                  'com.sonyericsson.rebuild.RebuildSettings')

+ 8
- 0
tests/properties/fixtures/authenticated_build.xml View File

@@ -0,0 +1,8 @@
1
+<?xml version="1.0" encoding="utf-8"?>
2
+<project>
3
+  <properties>
4
+    <hudson.security.AuthorizationMatrixProperty>
5
+      <permission>hudson.model.Item.Build:authenticated</permission>
6
+    </hudson.security.AuthorizationMatrixProperty>
7
+  </properties>
8
+</project>

+ 2
- 0
tests/properties/fixtures/authenticated_build.yaml View File

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

+ 20
- 0
tests/properties/fixtures/authorization_matrix.xml View File

@@ -0,0 +1,20 @@
1
+<?xml version="1.0" encoding="utf-8"?>
2
+<project>
3
+  <properties>
4
+    <hudson.security.AuthorizationMatrixProperty>
5
+      <permission>hudson.model.Item.Delete:admin</permission>
6
+      <permission>hudson.model.Item.Configure:admin</permission>
7
+      <permission>hudson.model.Item.Read:admin</permission>
8
+      <permission>hudson.model.Item.Discover:admin</permission>
9
+      <permission>hudson.model.Item.Build:admin</permission>
10
+      <permission>hudson.model.Item.Workspace:admin</permission>
11
+      <permission>hudson.model.Item.Cancel:admin</permission>
12
+      <permission>hudson.model.Run.Delete:admin</permission>
13
+      <permission>hudson.model.Run.Update:admin</permission>
14
+      <permission>hudson.scm.SCM.Tag:admin</permission>
15
+      <permission>hudson.model.Item.Discover:anonymous</permission>
16
+      <permission>hudson.model.Item.Read:anonymous</permission>
17
+      <permission>hudson.model.Item.ExtendedRead:anonymous</permission>
18
+    </hudson.security.AuthorizationMatrixProperty>
19
+  </properties>
20
+</project>

+ 17
- 0
tests/properties/fixtures/authorization_matrix.yaml View File

@@ -0,0 +1,17 @@
1
+properties:
2
+  - authorization:
3
+      admin:
4
+        - job-delete
5
+        - job-configure
6
+        - job-read
7
+        - job-discover
8
+        - job-build
9
+        - job-workspace
10
+        - job-cancel
11
+        - run-delete
12
+        - run-update
13
+        - scm-tag
14
+      anonymous:
15
+        - job-discover
16
+        - job-read
17
+        - job-extended-read

+ 8
- 0
tests/properties/fixtures/github.xml View File

@@ -0,0 +1,8 @@
1
+<?xml version="1.0" encoding="utf-8"?>
2
+<project>
3
+  <properties>
4
+    <com.coravy.hudson.plugins.github.GithubProjectProperty>
5
+      <projectUrl>https://github.com/openstack-infra/jenkins-job-builder/</projectUrl>
6
+    </com.coravy.hudson.plugins.github.GithubProjectProperty>
7
+  </properties>
8
+</project>

+ 3
- 0
tests/properties/fixtures/github.yaml View File

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

+ 8
- 0
tests/properties/fixtures/priority_sorter.xml View File

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

+ 3
- 0
tests/properties/fixtures/priority_sorter.yaml View File

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

+ 11
- 0
tests/properties/fixtures/promoted_build.xml View File

@@ -0,0 +1,11 @@
1
+<?xml version="1.0" encoding="utf-8"?>
2
+<project>
3
+  <properties>
4
+    <hudson.plugins.promoted__builds.JobPropertyImpl>
5
+      <activeProcessNames>
6
+        <string>Release to QA</string>
7
+        <string>Jane Must Approve</string>
8
+      </activeProcessNames>
9
+    </hudson.plugins.promoted__builds.JobPropertyImpl>
10
+  </properties>
11
+</project>

+ 5
- 0
tests/properties/fixtures/promoted_build.yaml View File

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

+ 2
- 2
tests/properties/fixtures/throttle001.xml View File

@@ -2,14 +2,14 @@
2 2
 <project>
3 3
   <properties>
4 4
     <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
5
-      <maxConcurrentPerNode>0</maxConcurrentPerNode>
5
+      <maxConcurrentPerNode>2</maxConcurrentPerNode>
6 6
       <maxConcurrentTotal>4</maxConcurrentTotal>
7 7
       <throttleEnabled>true</throttleEnabled>
8 8
       <categories>
9 9
         <string>cat1</string>
10 10
         <string>cat2</string>
11 11
       </categories>
12
-      <throttleOption/>
12
+      <throttleOption>category</throttleOption>
13 13
       <configVersion>1</configVersion>
14 14
     </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
15 15
   </properties>

+ 2
- 0
tests/properties/fixtures/throttle001.yaml View File

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

+ 16
- 0
tests/properties/fixtures/throttle002.xml View File

@@ -0,0 +1,16 @@
1
+<?xml version="1.0" encoding="utf-8"?>
2
+<project>
3
+  <properties>
4
+    <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
5
+      <maxConcurrentPerNode>0</maxConcurrentPerNode>
6
+      <maxConcurrentTotal>0</maxConcurrentTotal>
7
+      <throttleEnabled>true</throttleEnabled>
8
+      <categories>
9
+        <string>cat1</string>
10
+        <string>cat2</string>
11
+      </categories>
12
+      <throttleOption>project</throttleOption>
13
+      <configVersion>1</configVersion>
14
+    </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
15
+  </properties>
16
+</project>

+ 6
- 0
tests/properties/fixtures/throttle002.yaml View File

@@ -0,0 +1,6 @@
1
+properties:
2
+  - throttle:
3
+      categories:
4
+        - cat1
5
+        - cat2
6
+      option: project

Loading…
Cancel
Save