From 639d10d5c47500caed152fea3fd5ed9acf81d886 Mon Sep 17 00:00:00 2001
From: "James E. Blair" <jeblair@redhat.com>
Date: Fri, 9 Jun 2017 09:03:15 -0700
Subject: [PATCH] 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              |  3 ++
 doc/source/conf.py      |  1 +
 doc/source/index.rst    |  2 ++
 doc/source/jobs.rst     |  7 +++++
 zuul_sphinx/__init__.py |  0
 zuul_sphinx/zuul.py     | 63 +++++++++++++++++++++++++++++++++++++++++
 6 files changed, 76 insertions(+)
 create mode 100644 doc/source/jobs.rst
 create mode 100644 zuul_sphinx/__init__.py
 create mode 100644 zuul_sphinx/zuul.py

diff --git a/.gitignore b/.gitignore
index 32ebbc988..58948d485 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
+*.pyc
+*~
+
 # Unit test / coverage reports
 .coverage
 .tox
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 35fa016ef..bee6425ae 100755
--- a/doc/source/conf.py
+++ b/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'
 ]
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 63efd8395..092f1c1e9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,8 +1,10 @@
 .. include:: ../../README.rst
 
+
 .. toctree::
    :maxdepth: 2
 
+   jobs
    roles
 
 Indices and tables
diff --git a/doc/source/jobs.rst b/doc/source/jobs.rst
new file mode 100644
index 000000000..a3018478c
--- /dev/null
+++ b/doc/source/jobs.rst
@@ -0,0 +1,7 @@
+Jobs
+=====
+
+python35
+--------
+.. zuul:job:: python35
+
diff --git a/zuul_sphinx/__init__.py b/zuul_sphinx/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/zuul_sphinx/zuul.py b/zuul_sphinx/zuul.py
new file mode 100644
index 000000000..2409d8108
--- /dev/null
+++ b/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)