summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJames E. Blair <jeblair@redhat.com>2017-08-11 15:04:23 -0700
committerJames E. Blair <jeblair@redhat.com>2017-08-11 15:04:23 -0700
commitad1188ba7fff851633f57ddd46324a61eebe68fe (patch)
tree63499c9d9cf4fef39ff7e0177230b73cfbd8ee98
parent1cb9f8fa028c5a6d27e7089c482b6f57cbe8d9e1 (diff)
Add jobvar and rolevar directives0.1.5
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
Notes
Notes (review): Code-Review+2: Paul Belanger <pabelanger@redhat.com> Code-Review+2: David Shrewsbury <shrewsbury.dave@gmail.com> Workflow+1: David Shrewsbury <shrewsbury.dave@gmail.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Mon, 14 Aug 2017 17:03:58 +0000 Reviewed-on: https://review.openstack.org/493248 Project: openstack-infra/zuul-sphinx Branch: refs/heads/master
-rw-r--r--doc/source/example-jobs.rst36
-rw-r--r--doc/source/example-roles.rst33
-rw-r--r--doc/source/examples.rst63
-rw-r--r--doc/source/index.rst2
-rw-r--r--zuul_sphinx/zuul.py33
5 files changed, 102 insertions, 65 deletions
diff --git a/doc/source/example-jobs.rst b/doc/source/example-jobs.rst
new file mode 100644
index 0000000..26dfff8
--- /dev/null
+++ b/doc/source/example-jobs.rst
@@ -0,0 +1,36 @@
1Example Jobs
2============
3
4Jobs
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
34This is a job role: :job:`example`
35
36This is a job variable role: :jobvar:`example.foo.bar`
diff --git a/doc/source/example-roles.rst b/doc/source/example-roles.rst
new file mode 100644
index 0000000..827bef0
--- /dev/null
+++ b/doc/source/example-roles.rst
@@ -0,0 +1,33 @@
1Example Roles
2=============
3
4Roles
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
31This is an (Ansible) role (Sphinx) role: :role:`example`
32
33This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
index 9ab3866..ad175cb 100644
--- a/doc/source/examples.rst
+++ b/doc/source/examples.rst
@@ -1,69 +1,6 @@
1Examples 1Examples
2======== 2========
3 3
4Jobs
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
33This is a job role: :job:`example-job`
34
35This is a job variable role: :var:`example-job.foo.bar`
36
37Roles
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
63This is an (Ansible) role (Sphinx) role: :role:`example-role`
64
65This is an (Ansible) role variable (Sphinx) role: :var:`example-role.items.baz`
66
67Configuration Attributes 4Configuration Attributes
68------------------------ 5------------------------
69 6
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 31cbc73..a08c6d1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -4,6 +4,8 @@
4 :maxdepth: 2 4 :maxdepth: 2
5 5
6 examples 6 examples
7 example-jobs
8 example-roles
7 9
8Indices and tables 10Indices and tables
9================== 11==================
diff --git a/zuul_sphinx/zuul.py b/zuul_sphinx/zuul.py
index d8383a9..7cfb9c7 100644
--- a/zuul_sphinx/zuul.py
+++ b/zuul_sphinx/zuul.py
@@ -124,6 +124,8 @@ class ZuulObjectDescription(ZuulDirective, ObjectDescription):
124 object_names = { 124 object_names = {
125 'attr': 'attribute', 125 'attr': 'attribute',
126 'var': 'variable', 126 'var': 'variable',
127 'jobvar': 'job variable',
128 'rolevar': 'role variable',
127 } 129 }
128 130
129 def get_path(self): 131 def get_path(self):
@@ -265,6 +267,7 @@ class ZuulVarDirective(ZuulObjectDescription):
265 267
266 option_spec = { 268 option_spec = {
267 'type': lambda x: x, 269 'type': lambda x: x,
270 'default': lambda x: x,
268 'hidden': lambda x: x, 271 'hidden': lambda x: x,
269 'noindex': lambda x: x, 272 'noindex': lambda x: x,
270 } 273 }
@@ -299,12 +302,32 @@ class ZuulVarDirective(ZuulObjectDescription):
299 if 'hidden' in self.options: 302 if 'hidden' in self.options:
300 return sig 303 return sig
301 path = self.get_display_path() 304 path = self.get_display_path()
305 signode['is_multiline'] = True
306 line = addnodes.desc_signature_line()
307 line['add_permalink'] = True
302 for x in path: 308 for x in path:
303 signode += addnodes.desc_addname(x + '.', x + '.') 309 line += addnodes.desc_addname(x + '.', x + '.')
304 signode += addnodes.desc_name(sig, sig) 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 return sig 320 return sig
306 321
307 322
323class ZuulJobVarDirective(ZuulVarDirective):
324 pass
325
326
327class ZuulRoleVarDirective(ZuulVarDirective):
328 pass
329
330
308class ZuulStatDirective(ZuulObjectDescription): 331class ZuulStatDirective(ZuulObjectDescription):
309 has_content = True 332 has_content = True
310 333
@@ -414,6 +437,8 @@ class ZuulDomain(Domain):
414 'value': ZuulValueDirective, 437 'value': ZuulValueDirective,
415 'var': ZuulVarDirective, 438 'var': ZuulVarDirective,
416 'stat': ZuulStatDirective, 439 'stat': ZuulStatDirective,
440 'jobvar': ZuulJobVarDirective,
441 'rolevar': ZuulRoleVarDirective,
417 # Autodoc directives 442 # Autodoc directives
418 'autojob': ZuulAutoJobDirective, 443 'autojob': ZuulAutoJobDirective,
419 'autojobs': ZuulAutoJobsDirective, 444 'autojobs': ZuulAutoJobsDirective,
@@ -435,6 +460,10 @@ class ZuulDomain(Domain):
435 warn_dangling=True), 460 warn_dangling=True),
436 'stat': XRefRole(innernodeclass=nodes.inline, # type: ignore 461 'stat': XRefRole(innernodeclass=nodes.inline, # type: ignore
437 warn_dangling=True), 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 initial_data = { 469 initial_data = {