Add config option to find other roles

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

View File

@ -2,3 +2,11 @@ Zuul Sphinx
===========
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/``)

View File

@ -164,14 +164,20 @@ class ZuulDirective(Directive):
return lines
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
_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']
for p in os.listdir(roledir):
role_readme = os.path.join(roledir, p, 'README.rst')
if os.path.exists(role_readme):
roles[p] = role_readme
for d in role_dirs:
for p in os.listdir(d):
role_readme = os.path.join(d, p, 'README.rst')
if os.path.exists(role_readme):
roles[p] = role_readme
@property
def zuul_role_paths(self):
@ -613,4 +619,5 @@ class ZuulDomain(Domain):
def setup(app):
app.add_config_value('zuul_role_paths', [], 'html')
app.add_domain(ZuulDomain)