From 0a37793cdc045801d3f908f010a5f850b3b75f2f Mon Sep 17 00:00:00 2001 From: "Gael Chamoulaud (Strider)" Date: Tue, 8 Jun 2021 12:51:18 +0200 Subject: [PATCH] [validation_init] Remove the creation of a README.md file for a new validation This patch removes the creation of a role README.md file during the creation of a new validation with the validation_init role and adds documentation directly in the sphinx role documentation file. All variables are documented using comment(s) and will be rendered automatically by the ansible-autodoc.py script during the sphinx build. Signed-off-by: Gael Chamoulaud (Strider) Change-Id: I4341483264dbe657066f03a132ee83943e4aa823 --- doc/source/roles/role-validation_init.rst | 42 ++++++++++++++++- roles/validation_init/README.md | 47 ------------------- roles/validation_init/defaults/main.yml | 19 ++++++++ .../_skeleton_role_/defaults/main.yml.j2 | 7 +++ .../files/_skeleton_role_/vars/main.yml.j2 | 5 ++ roles/validation_init/tasks/main.yml | 45 +++++++++++++++--- roles/validation_init/templates/README.md.j2 | 39 --------------- 7 files changed, 111 insertions(+), 93 deletions(-) delete mode 100644 roles/validation_init/README.md delete mode 100644 roles/validation_init/templates/README.md.j2 diff --git a/doc/source/roles/role-validation_init.rst b/doc/source/roles/role-validation_init.rst index 2d699e909..afb51c7c8 100644 --- a/doc/source/roles/role-validation_init.rst +++ b/doc/source/roles/role-validation_init.rst @@ -2,7 +2,47 @@ validation_init =============== -.. literalinclude:: ../../../roles/validation_init/README.md +-------------- +About The Role +-------------- + +The ``validation_init`` role aims to create new validation from a skeleton. + +Requirements +============ + +None. + +Dependencies +============ + +None. + +Example Playbook +================ + +.. code-block:: yaml + + - name: Create my new role + hosts: localhost + connection: local + gather_facts: false + roles: + - { role: validation_init, validation_init_role_name: "mynewrolename"} + +License +======= + +Apache + +Author Information +================== + +**Red Hat TripleO DFG:DF Squad:VF** + +---------------- +Full Description +---------------- .. ansibleautoplugin:: :role: roles/validation_init diff --git a/roles/validation_init/README.md b/roles/validation_init/README.md deleted file mode 100644 index bd042cb5a..000000000 --- a/roles/validation_init/README.md +++ /dev/null @@ -1,47 +0,0 @@ -Validation_init -=============== - -The purpose of this `validation_init` role is to create new validation from a skeleton. - -Requirements ------------- - -None. - -Role Variables --------------- - -* `validation_init_debug`: <'false'> -- Debugging mode. -* `validation_init_role_name`: <'Undefined'> -- New role name, undefined by default! -* `validation_init_prefix`: <'tripleo'> -- New role prefix -* `validation_init_skeleton_role_dir`: <'/tmp'> -- Absolute path of the directory where the skeleton will be deployed -* `validation_init_roles_dir`: <'roles'> -- Absolute/Relative path to the roles directory where the new roles will be created -* `validation_init_zuuld_molecule`: <'zuul.d/molecule.yaml'> -- Relative path to the CI molecule yaml file -* `validation_init_playbooks_dir`: <'playbooks'> -- Relative path to the playbooks directory where the new playbook will be created -* `validation_init_roles_doc_dir`: <'doc/source/roles'> -- Relative path to documentation roles directory -* `validation_init_enabling_ci`: <'true'> -- If 'true', documentation and CI configuration will be done, otherwise not - -Dependencies ------------- - -None. - -Example Playbook ----------------- - - - name: Create my new role - hosts: localhost - connection: local - gather_facts: false - roles: - - { role: validation_init, validation_init_role_name: "mynewrolename"} - -License -------- - -Apache - -Author Information ------------------- - -Red hat TripleO DFG:DF Squad:VF diff --git a/roles/validation_init/defaults/main.yml b/roles/validation_init/defaults/main.yml index 2115b2731..ef048ecc0 100644 --- a/roles/validation_init/defaults/main.yml +++ b/roles/validation_init/defaults/main.yml @@ -18,11 +18,30 @@ # All variables intended for modification should place placed in this file. # All variables within this role should have a prefix of "validation_init" + +# Debugging mode validation_init_debug: false + +# New role prefix validation_init_prefix: "tripleo" + +# Absolute path of the directory where the skeletin will be deployed validation_init_skeleton_role_dir: "/tmp" + +# Absolute/Relative path to the roles directory where the new role will be +# created validation_init_roles_dir: "roles" + +# Absolute/Relative path to the CI molecule yaml file validation_init_zuuld_molecule: "zuul.d/molecule.yaml" + +# Absolute/Relative path to the playbooks directory where the new playbook will +# be created validation_init_playbooks_dir: "playbooks" + +# Absolute/Relative path to the documentation roles directory validation_init_roles_doc_dir: "doc/source/roles" + +# If 'true', the documentation and CI configuration will be created, otherwise not. +# Will be used to create new custom validation through the CLI. validation_init_enabling_ci: true diff --git a/roles/validation_init/files/_skeleton_role_/defaults/main.yml.j2 b/roles/validation_init/files/_skeleton_role_/defaults/main.yml.j2 index 76178d74d..638ccb9a6 100644 --- a/roles/validation_init/files/_skeleton_role_/defaults/main.yml.j2 +++ b/roles/validation_init/files/_skeleton_role_/defaults/main.yml.j2 @@ -17,5 +17,12 @@ # All variables intended for modification should place placed in this file. +# !!!! IMPORTANT !!!! +# Add a comment above every variables describing them. +# This will be included in the sphinx role documentation +# !!!! IMPORTANT !!!! + # All variables within this role should have a prefix of "{{ role_name | replace('-', '_') }}" + +# Debugging mode {{ role_name | replace('-', '_') }}_debug: false diff --git a/roles/validation_init/files/_skeleton_role_/vars/main.yml.j2 b/roles/validation_init/files/_skeleton_role_/vars/main.yml.j2 index a3ff0cfe1..5381f2e92 100644 --- a/roles/validation_init/files/_skeleton_role_/vars/main.yml.j2 +++ b/roles/validation_init/files/_skeleton_role_/vars/main.yml.j2 @@ -20,3 +20,8 @@ # intended to be modified. # All variables within this role should have a prefix of "{{ role_name }}" + +# !!!! IMPORTANT !!!! +# Add a comment above every variables describing them. +# This will be included in the sphinx role documentation +# !!!! IMPORTANT !!!! diff --git a/roles/validation_init/tasks/main.yml b/roles/validation_init/tasks/main.yml index 008d889a1..bb64a0bbd 100644 --- a/roles/validation_init/tasks/main.yml +++ b/roles/validation_init/tasks/main.yml @@ -62,11 +62,6 @@ args: creates: "{{ validation_init_roles_dir }}/{{ validation_init_prefix }}_{{ _role_name }}" -- name: Create overcloud deploy script - template: - src: README.md.j2 - dest: "{{ validation_init_roles_dir }}/{{ validation_init_prefix }}_{{_role_name }}/README.md" - - name: Create the playbook copy: content: | @@ -173,7 +168,45 @@ {{ opening }} {{ '=' * (opening | length) }} - .. literalinclude:: ../../../roles/{{ validation_init_prefix }}_{{ _role_name}}/README.md + -------------- + About The Role + -------------- + + + + Requirements + ============ + + + + Dependencies + ============ + + + + Example Playbook + ================ + + .. code-block:: yaml + + - hosts: localhost + gather_facts: false + roles: + - { role: {{ validation_init_prefix }}_{{ _role_name }} } + + Licence + ======= + + Apache + + Author Information + ================== + + **Red Hat TripleO DFG: Squad:** + + ---------------- + Full Description + ---------------- .. ansibleautoplugin:: :role: {{ validation_init_roles_dir }}/{{ validation_init_prefix }}_{{ _role_name }} diff --git a/roles/validation_init/templates/README.md.j2 b/roles/validation_init/templates/README.md.j2 deleted file mode 100644 index f06e9a9f3..000000000 --- a/roles/validation_init/templates/README.md.j2 +++ /dev/null @@ -1,39 +0,0 @@ -{{ role_name | replace('-', '_') | capitalize }} -{{ "%s" | format((role_name | replace('-', '_') | length) * "=") }} - -A brief description of the role goes here. - -Requirements ------------- - -Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required. - -Role Variables --------------- - -* `{{ role_name | replace('-', '_') }}_debug`: <'false'> -- Debugging mode. -* ... - -Dependencies ------------- - -A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles. - -Example Playbook ----------------- - -Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: - - - hosts: localhost - roles: - - { role: {{ role_name | replace('-', '_') }}, x: 42 } - -License -------- - -Apache - -Author Information ------------------- - -Red hat TripleO DFG: Squad: