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>
This commit is contained in:
Kevin Carter 2019-06-14 16:01:08 -05:00
parent 196bee0821
commit 53eddac2de
No known key found for this signature in database
GPG Key ID: CE94BD890A47B20A
8 changed files with 104 additions and 12 deletions

View File

@ -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

View File

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

9
doc/source/roles.rst Normal file
View File

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

View File

@ -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.

View File

@ -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.

View File

@ -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"

View File

@ -131,5 +131,5 @@ commands =
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