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

doc/source/example-jobs.rst

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

doc/source/example-roles.rst

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

doc/source/examples.rst

@@ -1,69 +1,6 @@
 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
 ------------------------
 

doc/source/index.rst

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

zuul_sphinx/zuul.py

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