Browse Source

Add jobvar and rolevar directives

Jobs and Roles frequently have the same variable names, so use
create unique directives and roles for each so that they are
easy to disambiguate.

This lets us say :jobvar:`tox.environment` rather than
:var:`job-tox.environment` which seems a bit arbitrary.

Change-Id: I9d72d11bfdb700037a6a08f92a2dbfa95ee519ad
James E. Blair 1 year ago
parent
commit
ad1188ba7f
5 changed files with 102 additions and 65 deletions
  1. 36
    0
      doc/source/example-jobs.rst
  2. 33
    0
      doc/source/example-roles.rst
  3. 0
    63
      doc/source/examples.rst
  4. 2
    0
      doc/source/index.rst
  5. 31
    2
      zuul_sphinx/zuul.py

+ 36
- 0
doc/source/example-jobs.rst View File

@@ -0,0 +1,36 @@
1
+Example Jobs
2
+============
3
+
4
+Jobs
5
+----
6
+
7
+.. job:: example
8
+
9
+   This is an example job.
10
+
11
+   .. jobvar:: foo
12
+
13
+      This is a variable used by this job.
14
+
15
+      .. jobvar:: bar
16
+         :default: zero
17
+
18
+         This is a sub key.
19
+
20
+   .. jobvar:: items
21
+      :type: list
22
+
23
+      This variable is a list.
24
+
25
+      .. jobvar:: baz
26
+
27
+         This is an item in a list.
28
+
29
+.. job:: example
30
+   :variant: stable
31
+
32
+   This is a variant of :job:`example` which runs on stable branches.
33
+
34
+This is a job role: :job:`example`
35
+
36
+This is a job variable role: :jobvar:`example.foo.bar`

+ 33
- 0
doc/source/example-roles.rst View File

@@ -0,0 +1,33 @@
1
+Example Roles
2
+=============
3
+
4
+Roles
5
+-----
6
+
7
+.. role:: example
8
+
9
+   This is an example role.
10
+
11
+   **Role Variables**
12
+
13
+   .. rolevar:: foo
14
+
15
+      This is a variable used by this role.
16
+
17
+      .. rolevar:: bar
18
+         :default: zero
19
+
20
+         This is a sub key.
21
+
22
+   .. rolevar:: items
23
+      :type: list
24
+
25
+      This variable is a list.
26
+
27
+      .. rolevar:: baz
28
+
29
+         This is an item in a list.
30
+
31
+This is an (Ansible) role (Sphinx) role: :role:`example`
32
+
33
+This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`

+ 0
- 63
doc/source/examples.rst View File

@@ -1,69 +1,6 @@
1 1
 Examples
2 2
 ========
3 3
 
4
-Jobs
5
-----
6
-
7
-.. job:: example-job
8
-
9
-   This is an example job.
10
-
11
-   .. var:: foo
12
-
13
-      This is a variable used by this job.
14
-
15
-      .. var:: bar
16
-
17
-         This is a sub key.
18
-
19
-   .. var:: items
20
-      :type: list
21
-
22
-      This variable is a list.
23
-
24
-      .. var:: baz
25
-
26
-         This is an item in a list.
27
-
28
-.. job:: example-job
29
-   :variant: stable
30
-
31
-   This is a variant of :job:`example-job` which runs on stable branches.
32
-
33
-This is a job role: :job:`example-job`
34
-
35
-This is a job variable role: :var:`example-job.foo.bar`
36
-
37
-Roles
38
------
39
-
40
-.. role:: example-role
41
-
42
-   This is an example role.
43
-
44
-   **Role Variables**
45
-
46
-   .. var:: foo
47
-
48
-      This is a variable used by this role.
49
-
50
-      .. var:: bar
51
-
52
-         This is a sub key.
53
-
54
-   .. var:: items
55
-      :type: list
56
-
57
-      This variable is a list.
58
-
59
-      .. var:: baz
60
-
61
-         This is an item in a list.
62
-
63
-This is an (Ansible) role (Sphinx) role: :role:`example-role`
64
-
65
-This is an (Ansible) role variable (Sphinx) role: :var:`example-role.items.baz`
66
-
67 4
 Configuration Attributes
68 5
 ------------------------
69 6
 

+ 2
- 0
doc/source/index.rst View File

@@ -4,6 +4,8 @@
4 4
    :maxdepth: 2
5 5
 
6 6
    examples
7
+   example-jobs
8
+   example-roles
7 9
 
8 10
 Indices and tables
9 11
 ==================

+ 31
- 2
zuul_sphinx/zuul.py View File

@@ -124,6 +124,8 @@ class ZuulObjectDescription(ZuulDirective, ObjectDescription):
124 124
     object_names = {
125 125
         'attr': 'attribute',
126 126
         'var': 'variable',
127
+        'jobvar': 'job variable',
128
+        'rolevar': 'role variable',
127 129
     }
128 130
 
129 131
     def get_path(self):
@@ -265,6 +267,7 @@ class ZuulVarDirective(ZuulObjectDescription):
265 267
 
266 268
     option_spec = {
267 269
         'type': lambda x: x,
270
+        'default': lambda x: x,
268 271
         'hidden': lambda x: x,
269 272
         'noindex': lambda x: x,
270 273
     }
@@ -299,12 +302,32 @@ class ZuulVarDirective(ZuulObjectDescription):
299 302
         if 'hidden' in self.options:
300 303
             return sig
301 304
         path = self.get_display_path()
305
+        signode['is_multiline'] = True
306
+        line = addnodes.desc_signature_line()
307
+        line['add_permalink'] = True
302 308
         for x in path:
303
-            signode += addnodes.desc_addname(x + '.', x + '.')
304
-        signode += addnodes.desc_name(sig, sig)
309
+            line += addnodes.desc_addname(x + '.', x + '.')
310
+        line += addnodes.desc_name(sig, sig)
311
+        if 'required' in self.options:
312
+            line += addnodes.desc_annotation(' (required)', ' (required)')
313
+        signode += line
314
+        if 'default' in self.options:
315
+            line = addnodes.desc_signature_line()
316
+            line += addnodes.desc_type('Default: ', 'Default: ')
317
+            line += nodes.literal(self.options['default'],
318
+                                  self.options['default'])
319
+            signode += line
305 320
         return sig
306 321
 
307 322
 
323
+class ZuulJobVarDirective(ZuulVarDirective):
324
+    pass
325
+
326
+
327
+class ZuulRoleVarDirective(ZuulVarDirective):
328
+    pass
329
+
330
+
308 331
 class ZuulStatDirective(ZuulObjectDescription):
309 332
     has_content = True
310 333
 
@@ -414,6 +437,8 @@ class ZuulDomain(Domain):
414 437
         'value': ZuulValueDirective,
415 438
         'var': ZuulVarDirective,
416 439
         'stat': ZuulStatDirective,
440
+        'jobvar': ZuulJobVarDirective,
441
+        'rolevar': ZuulRoleVarDirective,
417 442
         # Autodoc directives
418 443
         'autojob': ZuulAutoJobDirective,
419 444
         'autojobs': ZuulAutoJobsDirective,
@@ -435,6 +460,10 @@ class ZuulDomain(Domain):
435 460
                         warn_dangling=True),
436 461
         'stat': XRefRole(innernodeclass=nodes.inline,  # type: ignore
437 462
                          warn_dangling=True),
463
+        'jobvar': XRefRole(innernodeclass=nodes.inline,  # type: ignore
464
+                           warn_dangling=True),
465
+        'rolevar': XRefRole(innernodeclass=nodes.inline,  # type: ignore
466
+                            warn_dangling=True),
438 467
     }
439 468
 
440 469
     initial_data = {

Loading…
Cancel
Save