From 53eddac2de83730a0357ed187057eeb9713efc43 Mon Sep 17 00:00:00 2001 From: Kevin Carter Date: Fri, 14 Jun 2019 16:01:08 -0500 Subject: [PATCH] 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 --- doc/source/contributing.rst | 9 ++++++++- doc/source/index.rst | 1 + doc/source/roles.rst | 9 +++++++++ doc/source/roles/role-test_deps.rst | 23 +++++++++++++++++++++++ doc/source/roles/role-tuned.rst | 23 +++++++++++++++++++++++ role-addition.yml | 29 +++++++++++++++++++++++++++++ tox.ini | 6 +++--- zuul.d/layout.yaml | 16 ++++++++-------- 8 files changed, 104 insertions(+), 12 deletions(-) create mode 100644 doc/source/roles.rst create mode 100644 doc/source/roles/role-test_deps.rst create mode 100644 doc/source/roles/role-tuned.rst 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