Browse Source

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>
changes/75/665475/2
Kevin Carter 2 years ago
parent
commit
53eddac2de
No known key found for this signature in database GPG Key ID: CE94BD890A47B20A
  1. 9
      doc/source/contributing.rst
  2. 1
      doc/source/index.rst
  3. 9
      doc/source/roles.rst
  4. 23
      doc/source/roles/role-test_deps.rst
  5. 23
      doc/source/roles/role-tuned.rst
  6. 29
      role-addition.yml
  7. 6
      tox.ini
  8. 16
      zuul.d/layout.yaml

9
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

1
doc/source/index.rst

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

9
doc/source/roles.rst

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

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

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

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

6
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

16
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
Loading…
Cancel
Save