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
This commit is contained in:
James E. Blair 2017-06-09 09:03:15 -07:00
parent aaffa55dd1
commit 639d10d5c4
6 changed files with 76 additions and 0 deletions

3
.gitignore vendored
View File

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

View File

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

View File

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

7
doc/source/jobs.rst Normal file
View File

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

0
zuul_sphinx/__init__.py Normal file
View File

63
zuul_sphinx/zuul.py Normal file
View File

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