Ansible Role: make_role_readme

Generate Role markdown file (README.md) from meta data and a template. Inspired by and based on Jason Edelman's ansible-webdocs.

• Goal: Keep a somewhat consistent format for README.md and as Mr. Edelman states " if I didn’t end up creating this, I would have spent a ton of time manually creating tables in markdown one at a time for each [role] I was building! And just imagine making a small change like adding a row or column to each one!"

• Notes:

  • Since markdown and jinja are "funny", you may need extra line breaks and escaping to get things just right.

  • You can omit any variables in readme.yml, which will result in empty sections.

  • choices for a variable are supplied as a list.

  • Look at meta/readme.yml from this role to see how it was used to generate this README.md

---

Requirements

Copy readme.yml skeleton to role meta/ directory for every role. Modify as necessary.

---

Role Variables

variable	required	default	choices	comments
mr_md_filename	yes	README.md		The name of the markdown file to be generated.
mr_path_to_roles	yes	first path in roles_path		The path to your roles. DEFAULT_ROLES_PATH is used in defaults/main.yml
mr_role_name	yes			The name of the role.

---

Dependencies

You can place a list of galaxy roles here (use extra line breaks as necessary):

• example.dependency_role1
• example.dependency_role2

---

Example Playbooks

Maybe you want to place some extra text here to explain the following examples.

Create README.md for role 'aci_build'

- name: Generate Role(s) README.md
  hosts: localhost
  connection: local
  gather_facts: yes

  tasks:
    - name: include 'make_role_readme'
      include_role:
        name: make_role_readme
      vars:
        mr_role_name: aci_build

Supply a path to role(s)

- name: include 'make_role_readme'
  include_role:
    name: make_role_readme
  vars:
    mr_role_name: aci_build
    mr_path_to_roles: /aci_project/roles

Loop through multiple roles to create a README.md for each.

• Caveat - Escaping may be necessary in readme.yml.

- name: Generate Role(s) README.md
  hosts: localhost
  connection: local
  gather_facts: yes

  vars:
    mr_role_names:
      - make_role_readme
      - another_role
      - yet_another_role

  tasks:
    - name: include 'make_role_readme'
      include_role:
        name: make_role_readme
      vars:
        mr_role_name: "{{ mr_role_names_item }}"
      loop: "{{ mr_role_names }}"
      loop_control:
        loop_var: mr_role_names_item

---

Return Values

key	returned	description
return_val_example_1	when color == blue	Value is available as a fact that can be accessed, if and only if the value of color is blue.
return_val_example_2	always	A fact that is always returned and can be accessed as needed.

---

License

BSD

---

Author Information

Kris Vensl