diff --git a/doc/requirements.txt b/doc/requirements.txt
index 02aed5690c..858a5040ae 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,3 +1,3 @@
 sphinx!=1.6.6,!=1.6.7 # BSD
 openstackdocstheme>=1.11.0 # Apache-2.0
-
+zuul-sphinx>=0.1.1
diff --git a/doc/source/conf.py b/doc/source/conf.py
index c3c1580073..793ad8515d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -15,7 +15,15 @@ sys.path.insert(0, os.path.abspath('.'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['custom_roles', 'openstackdocstheme']
+extensions = ['custom_roles',
+              'openstackdocstheme',
+              'zuul_sphinx']
+
+# We have roles split between zuul-suitable roles at top level roles/*
+# (automatically detected by zuul-sphinx) and playbook-specific roles
+# (might have plugins, etc that make them unsuitable as potential zuul
+# roles).  Document both.
+zuul_role_paths = ['playbooks/roles']
 
 # openstackdocstheme options
 repository_name = 'openstack-infra/system-config'
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 7ac29cbb64..8d459dcb3b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -29,6 +29,7 @@ Contents:
    test-infra-requirements
    sysadmin
    systems
+   roles
 
 .. toctree::
    :hidden:
diff --git a/doc/source/roles.rst b/doc/source/roles.rst
new file mode 100644
index 0000000000..d7e0d4ee37
--- /dev/null
+++ b/doc/source/roles.rst
@@ -0,0 +1,8 @@
+:title: Roles
+
+Ansible Roles
+#############
+
+Documentation for roles included in `system-config`
+
+.. zuul:autoroles::
diff --git a/playbooks/roles/exim/README.rst b/playbooks/roles/exim/README.rst
index ad5e7ac675..2b6e7e4081 100644
--- a/playbooks/roles/exim/README.rst
+++ b/playbooks/roles/exim/README.rst
@@ -39,7 +39,7 @@ Installs and configures the exim mail server
    The maximum number of simultaneous incoming SMTP calls that Exim will
    accept. If the value is set to zero, no limit is applied. However, it
    is required to be non-zero if
-   :zuul:rolevar:`exim_smtp_accept_max_per_host` is set.
+   :zuul:rolevar:`exim.exim_smtp_accept_max_per_host` is set.
 
 .. zuul:rolevar:: exim_smtp_accept_max_per_host
    :default: null
@@ -51,4 +51,4 @@ Installs and configures the exim mail server
    additional connection attempts from the same host are rejected with error
    code 421. The option’s default value imposes no limit. If this option is
    set greater than zero, it is required that
-   :zuul:rolevar:`exim_smtp_accept_max` be non-zero.
+   :zuul:rolevar:`exim.exim_smtp_accept_max` be non-zero.
diff --git a/test-requirements.txt b/test-requirements.txt
index 79338a08a5..7e91d8cd73 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -6,3 +6,4 @@ bashate>=0.2 # Apache-2.0
 PyYAML>=3.10.0 # MIT
 ansible-lint
 openstacksdk
+zuul-sphinx>=0.2.3