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

README.rst

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

doc/source/conf.py

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

doc/source/example-autodoc.rst

@@ -10,3 +10,8 @@ Auto Project Templates
 ----------------------
 
 .. autoproject_templates::
+
+Auto Roles
+----------
+
+.. autoroles::

tests/roles/example-role/README.rst

@@ -0,0 +1,27 @@
+Example README.rst
+
+An example README.rst for a role
+
+**Role Variables**
+
+.. rolevar:: foo
+
+   This is a variable used by this role.
+
+   .. rolevar:: bar
+      :default: zero
+
+      This is a sub key.
+
+.. rolevar:: items
+   :type: list
+
+   This variable is a list.
+
+   .. rolevar:: baz
+
+   This is an item in a list.
+
+This is an (Ansible) role (Sphinx) role: :role:`example`
+
+This is an (Ansible) role variable (Sphinx) role: :rolevar:`example.items.baz`

zuul_sphinx/zuul.py

@@ -19,14 +19,19 @@ import os
 from sphinx import addnodes
 from docutils.parsers.rst import Directive
 from sphinx.domains import Domain, ObjType
+from sphinx.errors import SphinxError
 from sphinx.roles import XRefRole
 from sphinx.directives import ObjectDescription
+from sphinx.util import logging
 from sphinx.util.nodes import make_refnode
 from docutils import nodes
 
 import yaml
 
 
+logger = logging.getLogger(__name__)
+
+
 class ZuulSafeLoader(yaml.SafeLoader):
 
     def __init__(self, *args, **kwargs):
@@ -78,7 +83,7 @@ class ZuulDirective(Directive):
                 if os.path.exists(path):
                     return path
             root = os.path.split(root)[0]
-        raise Exception(
+        raise SphinxError(
             "Unable to find zuul config in zuul.yaml, .zuul.yaml,"
             " zuul.d or .zuul.d")
 
@@ -178,6 +183,12 @@ class ZuulDirective(Directive):
                 role_readme = os.path.join(d, p, 'README.rst')
                 if os.path.exists(role_readme):
                     roles[p] = role_readme
+                else:
+                    msg = "Missing role documentation: %s" % role_readme
+                    if env.config.zuul_autoroles_warn_missing:
+                        logger.warning(msg)
+                    else:
+                        logger.debug(msg)
 
     @property
     def zuul_role_paths(self):
@@ -620,4 +631,5 @@ class ZuulDomain(Domain):
 
 def setup(app):
     app.add_config_value('zuul_role_paths', [], 'html')
+    app.add_config_value('zuul_autoroles_warn_missing', True, '')
     app.add_domain(ZuulDomain)