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
This commit is contained in:
James E. Blair 2017-08-11 15:04:23 -07:00
parent 1cb9f8fa02
commit ad1188ba7f
5 changed files with 102 additions and 65 deletions

View File

@ -0,0 +1,36 @@
Example Jobs
============
Jobs
----
.. job:: example
This is an example job.
.. jobvar:: foo
This is a variable used by this job.
.. jobvar:: bar
:default: zero
This is a sub key.
.. jobvar:: items
:type: list
This variable is a list.
.. jobvar:: baz
This is an item in a list.
.. job:: example
:variant: stable
This is a variant of :job:`example` which runs on stable branches.
This is a job role: :job:`example`
This is a job variable role: :jobvar:`example.foo.bar`

View File

@ -0,0 +1,33 @@
Example Roles
=============
Roles
-----
.. role:: example
This is an example role.
**Role Variables**
.. rolevar:: foo
This is a variable used by this role.
.. rolevar:: bar
:default: zero
This is a sub key.
.. rolevar:: items
:type: list
This variable is a list.
.. rolevar:: baz
This is an item in a list.
This is an (Ansible) role (Sphinx) role: :role:`example`
This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`

View File

@ -1,69 +1,6 @@
Examples Examples
======== ========
Jobs
----
.. job:: example-job
This is an example job.
.. var:: foo
This is a variable used by this job.
.. var:: bar
This is a sub key.
.. var:: items
:type: list
This variable is a list.
.. var:: baz
This is an item in a list.
.. job:: example-job
:variant: stable
This is a variant of :job:`example-job` which runs on stable branches.
This is a job role: :job:`example-job`
This is a job variable role: :var:`example-job.foo.bar`
Roles
-----
.. role:: example-role
This is an example role.
**Role Variables**
.. var:: foo
This is a variable used by this role.
.. var:: bar
This is a sub key.
.. var:: items
:type: list
This variable is a list.
.. var:: baz
This is an item in a list.
This is an (Ansible) role (Sphinx) role: :role:`example-role`
This is an (Ansible) role variable (Sphinx) role: :var:`example-role.items.baz`
Configuration Attributes Configuration Attributes
------------------------ ------------------------

View File

@ -4,6 +4,8 @@
:maxdepth: 2 :maxdepth: 2
examples examples
example-jobs
example-roles
Indices and tables Indices and tables
================== ==================

View File

@ -124,6 +124,8 @@ class ZuulObjectDescription(ZuulDirective, ObjectDescription):
object_names = { object_names = {
'attr': 'attribute', 'attr': 'attribute',
'var': 'variable', 'var': 'variable',
'jobvar': 'job variable',
'rolevar': 'role variable',
} }
def get_path(self): def get_path(self):
@ -265,6 +267,7 @@ class ZuulVarDirective(ZuulObjectDescription):
option_spec = { option_spec = {
'type': lambda x: x, 'type': lambda x: x,
'default': lambda x: x,
'hidden': lambda x: x, 'hidden': lambda x: x,
'noindex': lambda x: x, 'noindex': lambda x: x,
} }
@ -299,12 +302,32 @@ class ZuulVarDirective(ZuulObjectDescription):
if 'hidden' in self.options: if 'hidden' in self.options:
return sig return sig
path = self.get_display_path() path = self.get_display_path()
signode['is_multiline'] = True
line = addnodes.desc_signature_line()
line['add_permalink'] = True
for x in path: for x in path:
signode += addnodes.desc_addname(x + '.', x + '.') line += addnodes.desc_addname(x + '.', x + '.')
signode += addnodes.desc_name(sig, sig) line += addnodes.desc_name(sig, sig)
if 'required' in self.options:
line += addnodes.desc_annotation(' (required)', ' (required)')
signode += line
if 'default' in self.options:
line = addnodes.desc_signature_line()
line += addnodes.desc_type('Default: ', 'Default: ')
line += nodes.literal(self.options['default'],
self.options['default'])
signode += line
return sig return sig
class ZuulJobVarDirective(ZuulVarDirective):
pass
class ZuulRoleVarDirective(ZuulVarDirective):
pass
class ZuulStatDirective(ZuulObjectDescription): class ZuulStatDirective(ZuulObjectDescription):
has_content = True has_content = True
@ -414,6 +437,8 @@ class ZuulDomain(Domain):
'value': ZuulValueDirective, 'value': ZuulValueDirective,
'var': ZuulVarDirective, 'var': ZuulVarDirective,
'stat': ZuulStatDirective, 'stat': ZuulStatDirective,
'jobvar': ZuulJobVarDirective,
'rolevar': ZuulRoleVarDirective,
# Autodoc directives # Autodoc directives
'autojob': ZuulAutoJobDirective, 'autojob': ZuulAutoJobDirective,
'autojobs': ZuulAutoJobsDirective, 'autojobs': ZuulAutoJobsDirective,
@ -435,6 +460,10 @@ class ZuulDomain(Domain):
warn_dangling=True), warn_dangling=True),
'stat': XRefRole(innernodeclass=nodes.inline, # type: ignore 'stat': XRefRole(innernodeclass=nodes.inline, # type: ignore
warn_dangling=True), warn_dangling=True),
'jobvar': XRefRole(innernodeclass=nodes.inline, # type: ignore
warn_dangling=True),
'rolevar': XRefRole(innernodeclass=nodes.inline, # type: ignore
warn_dangling=True),
} }
initial_data = { initial_data = {