Browse Source

Warn when autoroles doesn't find a README.rst

This modifies autoroles to raise a warning when it finds a role
without a README.rst file.  This can be disabled with a config option
if you wish to build with warning-as-error but don't wish to document
roles.

Fix a typo in the readme for the zuul_role_paths

Add a test for the autoroles path detection by including a roles
directory under a subdir.  Manually removing the README.rst file has
validated that the warning is triggered.

Change-Id: Ia64298e6e910d21eb6f3830dd8b42e40e3444fa8
Ian Wienand 8 months ago
parent
commit
a5136b73ad
5 changed files with 55 additions and 2 deletions
  1. 7
    1
      README.rst
  2. 3
    0
      doc/source/conf.py
  3. 5
    0
      doc/source/example-autodoc.rst
  4. 27
    0
      tests/roles/example-role/README.rst
  5. 13
    1
      zuul_sphinx/zuul.py

+ 7
- 1
README.rst View File

@@ -6,7 +6,13 @@ A Sphinx extension for documenting Zuul jobs.
6 6
 Config options
7 7
 --------------
8 8
 
9
-``zuul_role_path``
9
+``zuul_role_paths``
10 10
   (str list)
11 11
   List of extra paths to examine for role documentation (other than
12 12
   ``roles/``)
13
+
14
+``zuul_autoroles_warn_missing``
15
+  (boolean)
16
+  Default: True
17
+  Warn when a role found with ``autoroles`` does not have a
18
+  ``README.rst`` file.

+ 3
- 0
doc/source/conf.py View File

@@ -89,3 +89,6 @@ html_logo = '_static/logo.svg'
89 89
 # relative to this directory. They are copied after the builtin static files,
90 90
 # so a file named "default.css" will overwrite the builtin "default.css".
91 91
 html_static_path = ['_static']
92
+
93
+# Sample additional role paths
94
+zuul_role_paths = ['tests/roles']

+ 5
- 0
doc/source/example-autodoc.rst View File

@@ -10,3 +10,8 @@ Auto Project Templates
10 10
 ----------------------
11 11
 
12 12
 .. autoproject_templates::
13
+
14
+Auto Roles
15
+----------
16
+
17
+.. autoroles::

+ 27
- 0
tests/roles/example-role/README.rst View File

@@ -0,0 +1,27 @@
1
+Example README.rst
2
+
3
+An example README.rst for a role
4
+
5
+**Role Variables**
6
+
7
+.. rolevar:: foo
8
+
9
+   This is a variable used by this role.
10
+
11
+   .. rolevar:: bar
12
+      :default: zero
13
+
14
+      This is a sub key.
15
+
16
+.. rolevar:: items
17
+   :type: list
18
+
19
+   This variable is a list.
20
+
21
+   .. rolevar:: baz
22
+
23
+   This is an item in a list.
24
+
25
+This is an (Ansible) role (Sphinx) role: :role:`example`
26
+
27
+This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`

+ 13
- 1
zuul_sphinx/zuul.py View File

@@ -19,14 +19,19 @@ import os
19 19
 from sphinx import addnodes
20 20
 from docutils.parsers.rst import Directive
21 21
 from sphinx.domains import Domain, ObjType
22
+from sphinx.errors import SphinxError
22 23
 from sphinx.roles import XRefRole
23 24
 from sphinx.directives import ObjectDescription
25
+from sphinx.util import logging
24 26
 from sphinx.util.nodes import make_refnode
25 27
 from docutils import nodes
26 28
 
27 29
 import yaml
28 30
 
29 31
 
32
+logger = logging.getLogger(__name__)
33
+
34
+
30 35
 class ZuulSafeLoader(yaml.SafeLoader):
31 36
 
32 37
     def __init__(self, *args, **kwargs):
@@ -78,7 +83,7 @@ class ZuulDirective(Directive):
78 83
                 if os.path.exists(path):
79 84
                     return path
80 85
             root = os.path.split(root)[0]
81
-        raise Exception(
86
+        raise SphinxError(
82 87
             "Unable to find zuul config in zuul.yaml, .zuul.yaml,"
83 88
             " zuul.d or .zuul.d")
84 89
 
@@ -178,6 +183,12 @@ class ZuulDirective(Directive):
178 183
                 role_readme = os.path.join(d, p, 'README.rst')
179 184
                 if os.path.exists(role_readme):
180 185
                     roles[p] = role_readme
186
+                else:
187
+                    msg = "Missing role documentation: %s" % role_readme
188
+                    if env.config.zuul_autoroles_warn_missing:
189
+                        logger.warning(msg)
190
+                    else:
191
+                        logger.debug(msg)
181 192
 
182 193
     @property
183 194
     def zuul_role_paths(self):
@@ -620,4 +631,5 @@ class ZuulDomain(Domain):
620 631
 
621 632
 def setup(app):
622 633
     app.add_config_value('zuul_role_paths', [], 'html')
634
+    app.add_config_value('zuul_autoroles_warn_missing', True, '')
623 635
     app.add_domain(ZuulDomain)

Loading…
Cancel
Save