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.
 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.
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'
 # 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']
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
 ----------------------
 
 .. autoproject_templates::
+
+Auto Roles
+----------
+
+.. 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 @@
+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`
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
 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)