Create role documentation with Automated-Ansible-Role-Documentation

[rndmh3ro]

Description

The role's README should be automatically created. Currently we use https://github.com/telekom-mms/Automated-Ansible-Role-Documentation to create the README.

Solution

The configuration looks like this:

.aar-doc.yml

output_template: |
  <!-- BEGIN_ANSIBLE_DOCS -->
  ## Supported Operating Systems

  {%- for platform in metadata.galaxy_info.platforms %}
  - {{ platform.name }}
    {%- if "versions" in platform %}
    - {{ platform.versions | default([]) | join(', ') }}
    {%- endif %}
  {%- endfor %}

  ## Role Variables
  {% for entrypoint in argument_specs.keys() %}
  {%- set path, options=entrypoint_options[entrypoint][0] -%}
  {%- for name, details in options.items() |sort() %}
  - `{{ name }}`
    - Default: `{{ details.display_default }}`
    - Description: {{ details.display_description }}
    - Type: {{ details.display_type }}
    - Required: {{ details.display_required }}
  {%- endfor %}
  {%- endfor %}

  ## Dependencies

  {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
  {%- for dependency in metadata.dependencies %}
  - {{ dependency }}
  {%- endfor %}
  {%- else %}

  None.
  {%- endif %}

  ## Example Playbook


  - hosts: all
    roles:
      - name: {{ role }}


  <!-- END_ANSIBLE_DOCS -->

We need some Github Actions to automatically create the READMEs.
For the creation, it is important to know that the Role Variables are created from the contents of meta/argument_specs.yml. So if anyone wants to add new defaults, these have to get into the argument_spec, too (Maybe add this to the CONTRIBUTING guide).

Alternatives

No response

Additional information

...