diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index efc5768d0..d11d72677 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -39,7 +39,7 @@ When the role is ready for CI add a jobs entry into the `zuul.d/jobs.yaml`.
           tox_envlist: mol-${NEWROLENAME}
 
 
-And finally add the job into the `zuul.d/layout.yaml` file.
+Add the job into the `zuul.d/layout.yaml` file.
 
 .. code-block:: yaml
 
@@ -49,6 +49,13 @@ And finally add the job into the `zuul.d/layout.yaml` file.
             - tripleo-ansible-centos:mol-${NEWROLENAME}
 
 
+And finally add a role documentation file at
+`doc/source/roles/role-${NEWROLENAME}.rst`. This file will need to contain
+a title, a literal include of the defaults yaml and a literal include of
+the molecule playbook used to test the role, which is noted as an "example"
+playbook.
+
+
 The role addition process is also automated using ansible. If ansible is
 available on the development workstation change directory to the root of
 the `tripleo-ansible` repository and run the the following command which
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 24de9741c..2e9c5283c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -14,6 +14,7 @@ Contents:
    installation
    contributing
    usage
+   roles
 
 Indices and tables
 ==================
diff --git a/doc/source/roles.rst b/doc/source/roles.rst
new file mode 100644
index 000000000..a19a3f329
--- /dev/null
+++ b/doc/source/roles.rst
@@ -0,0 +1,9 @@
+Documented roles in TripleO-Ansible
+===================================
+
+Contents:
+
+.. toctree::
+   :glob:
+
+   roles/*
diff --git a/doc/source/roles/role-test_deps.rst b/doc/source/roles/role-test_deps.rst
new file mode 100644
index 000000000..90a6814d6
--- /dev/null
+++ b/doc/source/roles/role-test_deps.rst
@@ -0,0 +1,23 @@
+================================
+TripleO-Ansible Role - test_deps
+================================
+
+This role provides for the following services:
+
+    * test_deps
+
+
+Default variables
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../../tripleo_ansible/roles/test_deps/defaults/main.yml
+  :language: yaml
+  :start-after: under the License.
+
+
+Example playbook
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../../tripleo_ansible/roles/test_deps/molecule/default/playbook.yml
+  :language: yaml
+  :start-after: under the License.
diff --git a/doc/source/roles/role-tuned.rst b/doc/source/roles/role-tuned.rst
new file mode 100644
index 000000000..14e804f57
--- /dev/null
+++ b/doc/source/roles/role-tuned.rst
@@ -0,0 +1,23 @@
+============================
+TripleO-Ansible Role - tuned
+============================
+
+This role provides for the following services:
+
+    * tuned
+
+
+Default variables
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../../tripleo_ansible/roles/tuned/defaults/main.yml
+  :language: yaml
+  :start-after: under the License.
+
+
+Example playbook
+~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../../tripleo_ansible/roles/tuned/molecule/default/playbook.yml
+  :language: yaml
+  :start-after: under the License.
diff --git a/role-addition.yml b/role-addition.yml
index 459ba827d..6bb1937dc 100644
--- a/role-addition.yml
+++ b/role-addition.yml
@@ -101,3 +101,32 @@
           {% endfor %}
           {{ layouts | to_nice_yaml(indent=2, width=1337) }}
         dest: zuul.d/layout.yaml
+
+    - name: Create role documentation
+      copy:
+        content: |
+          {% set opening = 'TripleO-Ansible Role - ' ~ role_name %}
+          {{ '=' * (opening | length) }}
+          {{ opening }}
+          {{ '=' * (opening | length) }}
+
+          This role provides for the following services:
+
+              * {{ role_name }}
+
+
+          Default variables
+          ~~~~~~~~~~~~~~~~~
+
+          .. literalinclude:: ../../../tripleo_ansible/roles/{{ role_name }}/defaults/main.yml
+            :language: yaml
+            :start-after: under the License.
+
+
+          Example playbook
+          ~~~~~~~~~~~~~~~~
+
+          .. literalinclude:: ../../../tripleo_ansible/roles/{{ role_name }}/molecule/default/playbook.yml
+            :language: yaml
+            :start-after: under the License.
+        dest: "doc/source/roles/role-{{ role_name }}.rst"
diff --git a/tox.ini b/tox.ini
index e2d47391b..16dfd17bb 100644
--- a/tox.ini
+++ b/tox.ini
@@ -128,8 +128,8 @@ commands =
     python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py
 
 [testenv:mol-tuned]
-basepython={[testenv:mol]basepython}
-deps={[testenv:mol]deps}
+basepython = {[testenv:mol]basepython}
+deps = {[testenv:mol]deps}
 changedir = {toxinidir}/tripleo_ansible/roles/tuned
-commands =
+commands = python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py
     python -m pytest --color=yes --html={envlogdir}/reports.html --self-contained-html {tty:-s} {toxinidir}/tests/test_molecule.py
diff --git a/zuul.d/layout.yaml b/zuul.d/layout.yaml
index 04adbed7a..2b2a2bf15 100644
--- a/zuul.d/layout.yaml
+++ b/zuul.d/layout.yaml
@@ -2,16 +2,16 @@
 - project:
     check:
       jobs:
-        - openstack-tox-linters
-        - tripleo-ansible-centos-7-molecule-test_deps
-        - tripleo-ansible-centos-7-molecule-tuned
-        - tripleo-ansible-docs
+      - openstack-tox-linters
+      - tripleo-ansible-centos-7-molecule-test_deps
+      - tripleo-ansible-centos-7-molecule-tuned
+      - tripleo-ansible-docs
     gate:
       jobs:
-        - openstack-tox-linters
+      - openstack-tox-linters
     post:
       jobs:
-        - publish-openstack-python-branch-tarball
+      - publish-openstack-python-branch-tarball
     templates:
-      - publish-openstack-docs-pti
-      - release-notes-jobs-python3
+    - publish-openstack-docs-pti
+    - release-notes-jobs-python3