summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorIan Wienand <iwienand@redhat.com>2018-08-24 14:05:46 +1000
committerIan Wienand <iwienand@redhat.com>2018-08-24 14:09:22 +1000
commita5136b73add0b8b287859bd192135d78f5dd56a5 (patch)
tree00a5950ddc74944e27ce687c25795a8f2b7fa7de
parent046c5e548c7c42acc55fa4b5e58bab26786070e2 (diff)
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
Notes
Notes (review): Code-Review+2: Monty Taylor <mordred@inaugust.com> Code-Review+2: Clark Boylan <cboylan@sapwetik.org> Code-Review+2: Tobias Henkel <tobias.henkel@bmw.de> Workflow+1: Tobias Henkel <tobias.henkel@bmw.de> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Mon, 03 Sep 2018 12:10:41 +0000 Reviewed-on: https://review.openstack.org/596014 Project: openstack-infra/zuul-sphinx Branch: refs/heads/master
-rw-r--r--README.rst8
-rwxr-xr-xdoc/source/conf.py3
-rw-r--r--doc/source/example-autodoc.rst5
-rw-r--r--tests/roles/example-role/README.rst27
-rw-r--r--zuul_sphinx/zuul.py14
5 files changed, 55 insertions, 2 deletions
diff --git a/README.rst b/README.rst
index 814cfde..7b17f13 100644
--- a/README.rst
+++ b/README.rst
@@ -6,7 +6,13 @@ A Sphinx extension for documenting Zuul jobs.
6Config options 6Config options
7-------------- 7--------------
8 8
9``zuul_role_path`` 9``zuul_role_paths``
10 (str list) 10 (str list)
11 List of extra paths to examine for role documentation (other than 11 List of extra paths to examine for role documentation (other than
12 ``roles/``) 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.
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6aeb61a..8d4f735 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -89,3 +89,6 @@ html_logo = '_static/logo.svg'
89# relative to this directory. They are copied after the builtin static files, 89# relative to this directory. They are copied after the builtin static files,
90# so a file named "default.css" will overwrite the builtin "default.css". 90# so a file named "default.css" will overwrite the builtin "default.css".
91html_static_path = ['_static'] 91html_static_path = ['_static']
92
93# Sample additional role paths
94zuul_role_paths = ['tests/roles']
diff --git a/doc/source/example-autodoc.rst b/doc/source/example-autodoc.rst
index 770dbe5..1aa2043 100644
--- a/doc/source/example-autodoc.rst
+++ b/doc/source/example-autodoc.rst
@@ -10,3 +10,8 @@ Auto Project Templates
10---------------------- 10----------------------
11 11
12.. autoproject_templates:: 12.. autoproject_templates::
13
14Auto Roles
15----------
16
17.. autoroles::
diff --git a/tests/roles/example-role/README.rst b/tests/roles/example-role/README.rst
new file mode 100644
index 0000000..7730d2e
--- /dev/null
+++ b/tests/roles/example-role/README.rst
@@ -0,0 +1,27 @@
1Example README.rst
2
3An 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
25This is an (Ansible) role (Sphinx) role: :role:`example`
26
27This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`
diff --git a/zuul_sphinx/zuul.py b/zuul_sphinx/zuul.py
index df3895d..631afc9 100644
--- a/zuul_sphinx/zuul.py
+++ b/zuul_sphinx/zuul.py
@@ -19,14 +19,19 @@ import os
19from sphinx import addnodes 19from sphinx import addnodes
20from docutils.parsers.rst import Directive 20from docutils.parsers.rst import Directive
21from sphinx.domains import Domain, ObjType 21from sphinx.domains import Domain, ObjType
22from sphinx.errors import SphinxError
22from sphinx.roles import XRefRole 23from sphinx.roles import XRefRole
23from sphinx.directives import ObjectDescription 24from sphinx.directives import ObjectDescription
25from sphinx.util import logging
24from sphinx.util.nodes import make_refnode 26from sphinx.util.nodes import make_refnode
25from docutils import nodes 27from docutils import nodes
26 28
27import yaml 29import yaml
28 30
29 31
32logger = logging.getLogger(__name__)
33
34
30class ZuulSafeLoader(yaml.SafeLoader): 35class ZuulSafeLoader(yaml.SafeLoader):
31 36
32 def __init__(self, *args, **kwargs): 37 def __init__(self, *args, **kwargs):
@@ -78,7 +83,7 @@ class ZuulDirective(Directive):
78 if os.path.exists(path): 83 if os.path.exists(path):
79 return path 84 return path
80 root = os.path.split(root)[0] 85 root = os.path.split(root)[0]
81 raise Exception( 86 raise SphinxError(
82 "Unable to find zuul config in zuul.yaml, .zuul.yaml," 87 "Unable to find zuul config in zuul.yaml, .zuul.yaml,"
83 " zuul.d or .zuul.d") 88 " zuul.d or .zuul.d")
84 89
@@ -178,6 +183,12 @@ class ZuulDirective(Directive):
178 role_readme = os.path.join(d, p, 'README.rst') 183 role_readme = os.path.join(d, p, 'README.rst')
179 if os.path.exists(role_readme): 184 if os.path.exists(role_readme):
180 roles[p] = role_readme 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 @property 193 @property
183 def zuul_role_paths(self): 194 def zuul_role_paths(self):
@@ -620,4 +631,5 @@ class ZuulDomain(Domain):
620 631
621def setup(app): 632def setup(app):
622 app.add_config_value('zuul_role_paths', [], 'html') 633 app.add_config_value('zuul_role_paths', [], 'html')
634 app.add_config_value('zuul_autoroles_warn_missing', True, '')
623 app.add_domain(ZuulDomain) 635 app.add_domain(ZuulDomain)