Browse Source

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
Ian Wienand 8 months ago
parent
commit
06eadf8e73
2 changed files with 21 additions and 6 deletions
  1. 8
    0
      README.rst
  2. 13
    6
      zuul_sphinx/zuul.py

+ 8
- 0
README.rst View File

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

+ 13
- 6
zuul_sphinx/zuul.py View File

@@ -164,14 +164,20 @@ class ZuulDirective(Directive):
164 164
         return lines
165 165
 
166 166
     def find_zuul_roles(self):
167
-        root = os.path.dirname(self.zuul_layout_path)
168
-        roledir = os.path.join(root, 'roles')
169 167
         env = self.state.document.settings.env
168
+        _root = os.path.dirname(self.zuul_layout_path)
169
+        root_roledir = os.path.join(_root, 'roles')
170
+        role_dirs = []
171
+        if os.path.isdir(root_roledir):
172
+            role_dirs = [root_roledir,]
173
+        if env.config.zuul_role_paths:
174
+            role_dirs.extend(env.config.zuul_role_paths)
170 175
         roles = env.domaindata['zuul']['role_paths']
171
-        for p in os.listdir(roledir):
172
-            role_readme = os.path.join(roledir, p, 'README.rst')
173
-            if os.path.exists(role_readme):
174
-                roles[p] = role_readme
176
+        for d in role_dirs:
177
+            for p in os.listdir(d):
178
+                role_readme = os.path.join(d, p, 'README.rst')
179
+                if os.path.exists(role_readme):
180
+                    roles[p] = role_readme
175 181
 
176 182
     @property
177 183
     def zuul_role_paths(self):
@@ -613,4 +619,5 @@ class ZuulDomain(Domain):
613 619
 
614 620
 
615 621
 def setup(app):
622
+    app.add_config_value('zuul_role_paths', [], 'html')
616 623
     app.add_domain(ZuulDomain)

Loading…
Cancel
Save