Add role argument spec and action to auto-update readme (#233)

* update due to new release

* trigger workflow

* add role argument specification

* fix linting

* Add role argument spec for icinga role

* add argument spec and updated readme

* Revert "update due to new release"

This reverts commit 64b65ad.

* add workflow to update readme

* Apply suggestions from code review

Co-authored-by: schurzi <[email protected]>

---------

Co-authored-by: Deutsche Telekom MMS <[email protected]>
Co-authored-by: Sebastian Gumprich <[email protected]>
Co-authored-by: schurzi <[email protected]>

.aar_doc.yml

@@ -0,0 +1,72 @@
+output_template: |
+  <!-- BEGIN_ANSIBLE_DOCS -->
+  # Ansible Role: {{ role }}
+  ---
+  {%- if "version" in galaxy_collection %}
+  Version: {{ galaxy_collection.version }}
+  {% endif %}
+  {{ metadata.galaxy_info.description }}
+  {% if ("galaxy_tags" in metadata.galaxy_info) and (metadata.galaxy_info.galaxy_tags | length > 0) %}
+  Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
+  {%- endif %}
+
+  ## Requirements
+  ---
+  | Platform | Versions |
+  | -------- | -------- |
+  {%- for platform in metadata.galaxy_info.platforms %}
+  | {{ platform.name }} | {{ platform.versions | default([]) | join(', ') }} |
+  {%- endfor %}
+
+  ## 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 }}
+    {% if details.options -%}
+    - Options:
+      {% for key, value in details.options.items() %}
+      - `{{ key }}`:
+        - description:
+          {% for line in value.description %}
+          - "{{ line }}"
+          {% endfor %}
+          {%- if value.choices %}
+        - Choices:
+            {%- for choice in value.choices %}
+            - {{ choice }}
+            {%- endfor %}
+          {%- endif %}
+        - default: "{{ value.default }}"
+        - type: "{{ value.type }}"
+        - required: "{{ value.display_required }}"
+        {% endfor %}
+    {%- endif %}
+  {%- endfor %}
+  {%- endfor %}
+
+  ## Dependencies
+
+  {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
+  {%- for dependency in metadata.dependencies %}
+  - {{ dependency }}
+  {%- endfor %}
+  {%- else %}
+
+  None.
+  {%- endif %}
+
+  <!-- END_ANSIBLE_DOCS -->

.github/workflows/roles-readme.yml

@@ -0,0 +1,41 @@
+---
+name: create roles readme
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [main]
+    paths:
+      - 'roles/*/meta/argument_specs.yml'
+      - 'roles/*/meta/main.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'roles/*/meta/argument_specs.yml'
+      - 'roles/*/meta/main.yml'
+jobs:
+  readme:
+    name: create roles readme
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install aar_doc
+        run: pip3 install aar_doc
+
+      - name: Run aar_doc
+        run: aar_doc --config-file .aar_doc.yml roles/ansible_icinga/ markdown
+
+      - name: Push README
+        if: github.event_name != 'pull_request'
+        uses: github-actions-x/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: 'update readme'
+          files: README.md
+          rebase: true