Add Sphinx module for Zuul jobs

This adds a Sphinx module that includes the 'description' field of
a zuul job into the documentation.

Change-Id: Iaaf5d9c1013d6c1e788046db9dbf1278d786c01e

.gitignore

@@ -1,3 +1,6 @@
+*.pyc
+*~
+
 # Unit test / coverage reports
 .coverage
 .tox

doc/source/conf.py

@@ -23,6 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
+    'zuul_sphinx.zuul',
     'oslosphinx'
 ]
 

doc/source/index.rst

@@ -1,8 +1,10 @@
 .. include:: ../../README.rst
 
+
 .. toctree::
    :maxdepth: 2
 
+   jobs
    roles
 
 Indices and tables

doc/source/jobs.rst

@@ -0,0 +1,7 @@
+Jobs
+=====
+
+python35
+--------
+.. zuul:job:: python35
+

zuul_sphinx/zuul.py

@@ -0,0 +1,63 @@
+from docutils.parsers.rst import Directive
+from sphinx.domains import Domain, ObjType
+import os
+
+import yaml
+
+
+class Layout(object):
+    def __init__(self):
+        self.jobs = []
+
+
+class ZuulJobDirective(Directive):
+    has_content = True
+
+    def findZuulYaml(self):
+        root = self.state.document.settings.env.relfn2path('.')[1]
+        while root:
+            for fn in ['zuul.yaml', '.zuul.yaml']:
+                path = os.path.join(root, fn)
+                if os.path.exists(path):
+                    return path
+            root = os.path.split(root)[0]
+        raise Exception("Unable to find zuul.yaml or .zuul.yaml")
+
+    def parseZuulYaml(self, path):
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        layout = Layout()
+        for obj in data:
+            if 'job' in obj:
+                layout.jobs.append(obj['job'])
+        return layout
+
+    def run(self):
+        fn = self.findZuulYaml()
+        layout = self.parseZuulYaml(fn)
+        lines = None
+        for job in layout.jobs:
+            if job['name'] == self.content[0]:
+                lines = job.get('description', '')
+        if lines:
+            lines = lines.split('\n')
+
+        self.state_machine.insert_input(lines, fn)
+        return []
+
+
+class ZuulDomain(Domain):
+    name = 'zuul'
+    label = 'Zuul'
+
+    object_types = {
+        'job':  ObjType('job'),
+    }
+
+    directives = {
+        'job': ZuulJobDirective,
+    }
+
+
+def setup(app):
+    app.add_domain(ZuulDomain)