zuul/zuul-sphinx
Code Issues Proposed changes

Add config option to find other roles

Browse Source 
Add a new option to provide an additional list of directories to look
for roles to document.

Additionally, allow the 'roles/' top-level directory to not exist.

Needed-By: https://review.openstack.org/593478
Change-Id: I997c8bbece4917fe041aa9fd3dde13ee532fa2a6
This commit is contained in:
Ian Wienand 2018-08-20 13:21:32 +10:00
parent 44012c032b
commit 06eadf8e73
2 changed files with 21 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.rst
View File

@ -2,3 +2,11 @@ Zuul Sphinx
=========== ===========
A Sphinx extension for documenting Zuul jobs. A Sphinx extension for documenting Zuul jobs.
Config options
--------------
``zuul_role_path``
(str list)
List of extra paths to examine for role documentation (other than
``roles/``)

19
zuul_sphinx/zuul.py
View File

@ -164,14 +164,20 @@ class ZuulDirective(Directive):
return lines return lines
def find_zuul_roles(self): def find_zuul_roles(self):
root = os.path.dirname(self.zuul_layout_path)
roledir = os.path.join(root, 'roles')
env = self.state.document.settings.env env = self.state.document.settings.env
_root = os.path.dirname(self.zuul_layout_path)
root_roledir = os.path.join(_root, 'roles')
role_dirs = []
if os.path.isdir(root_roledir):
role_dirs = [root_roledir,]
if env.config.zuul_role_paths:
role_dirs.extend(env.config.zuul_role_paths)
roles = env.domaindata['zuul']['role_paths'] roles = env.domaindata['zuul']['role_paths']
for p in os.listdir(roledir): for d in role_dirs:
role_readme = os.path.join(roledir, p, 'README.rst') for p in os.listdir(d):
if os.path.exists(role_readme): role_readme = os.path.join(d, p, 'README.rst')
roles[p] = role_readme if os.path.exists(role_readme):
roles[p] = role_readme
@property @property
def zuul_role_paths(self): def zuul_role_paths(self):
@ -613,4 +619,5 @@ class ZuulDomain(Domain):
def setup(app): def setup(app):
app.add_config_value('zuul_role_paths', [], 'html')
app.add_domain(ZuulDomain) app.add_domain(ZuulDomain)