Add automatic documentation for new roles

When new roles are created following the contributing process,
documentation will now be automatically generated using the
role itself as content.

The automatic documentation process has been added to the
role-addition.yml playbook making it easy for developers to
get started.

Change-Id: Idba128e441a1a4fdff30ff1b9105f7ca8d199345
Signed-off-by: Kevin Carter <kecarter@redhat.com>

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

doc/source/index.rst

@@ -14,6 +14,7 @@ Contents:
    installation
    contributing
    usage
+   roles
 
 Indices and tables
 ==================

doc/source/roles.rst

@@ -0,0 +1,9 @@
+Documented roles in TripleO-Ansible
+===================================
+
+Contents:
+
+.. toctree::
+   :glob:
+
+   roles/*

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.

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.

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"

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

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