Generate roles documentation

Since we're building out roles in system-config now, generate
documentation.  We look in roles/* and playbook/roles/* (follow-on
changes will split things up between the two).

Correct the reference names in the exim documentation to avoid
warnings and failure.

This also revealed a single unicode character in the exim readme
(which caused prior versions of zuul-sphinx to barf).  For fun, see if
you can find it!

Depends-On: https://review.openstack.org/#/c/579474/
Change-Id: I243a96bbd6d09560f8aa80b6345b90039422547a

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

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'

doc/source/index.rst

@@ -29,6 +29,7 @@ Contents:
    test-infra-requirements
    sysadmin
    systems
+   roles
 
 .. toctree::
    :hidden:

doc/source/roles.rst

@@ -0,0 +1,8 @@
+:title: Roles
+
+Ansible Roles
+#############
+
+Documentation for roles included in `system-config`
+
+.. zuul:autoroles::

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.

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