[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) <gchamoul@redhat.com>
Change-Id: I4341483264dbe657066f03a132ee83943e4aa823

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

roles/validation_init/README.md

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

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

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

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

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
+          --------------
+
+          <Description of your role here>
+
+          Requirements
+          ============
+
+          <List all the requirements needed by this new role>
+
+          Dependencies
+          ============
+
+          <List all the dependencies needed by this new role>
+
+          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:<DFG_NAME> Squad:<SQUAD_NAME>**
+
+          ----------------
+          Full Description
+          ----------------
 
           .. ansibleautoplugin::
             :role: {{ validation_init_roles_dir }}/{{ validation_init_prefix }}_{{ _role_name }}

roles/validation_init/templates/README.md.j2

@@ -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:<dfg_name> Squad:<squad_name>