Merge pull request #1 from punktDe/aar-doc

infra_role: Add aar-doc config

Author: medanthelinium

proserver_init/infra.py

@@ -44,6 +44,7 @@ def init_role(self, from_path, to_path):
         role_name = os.path.split(to_path)[1]
         config = {
                 "role_name": role_name,
+                "role_name_short": role_name.removeprefix("ansible-proserver-").removeprefix("ansible-")
                 }
         ConfigWriter(from_path, to_path, config, flavor=None).write_configs()
         os.chdir(to_path)

proserver_init/templates/infra_role/generic/.aar-doc.yml.template

@@ -0,0 +1,98 @@
+---
+output_file: README.md
+output_mode: replace
+output_template: |
+  <!-- BEGIN_ANSIBLE_DOCS -->
+  # {{ role }}
+
+  {{ metadata.galaxy_info.description }}
+
+  ## Supported Operating Systems
+
+  - Debian 12
+  - Ubuntu 24.04, 22.04
+  - FreeBSD [Proserver](https://infrastructure.punkt.de/de/produkte/proserver.html)
+
+  ## Role Arguments
+
+  {% for entrypoint in argument_specs.keys() %}
+
+  {% if "description" in argument_specs[entrypoint] %}
+  {%- if argument_specs[entrypoint].description is string -%}
+  {{ argument_specs[entrypoint].description }}
+  {% else %}
+  {%- for line in argument_specs[entrypoint].description -%}
+  {{ line }}
+
+  {% endfor -%}
+  {% endif -%}
+  {% endif -%}
+
+  {% if entrypoint_options[entrypoint] | length > 1 -%}
+  {% for path, options in entrypoint_options[entrypoint][1:] -%}
+  #### Options for `{{ path | reject('eq', 'main') | join(".") }}`
+
+  |Option|Description|Type|Required|Default|
+  |---|---|---|---|---|
+  {%- for name, details in options.items() %}
+  | `{{ name }}` | {{ details.display_description }} | {{ details.display_type }} | {{ details.display_required }} | {{ details.display_default }} |
+  {%- endfor %}
+
+  {% endfor -%}
+
+  {% endif -%}
+
+  {% if entrypoint in entrypoint_choices -%}
+  {% for path, choices in entrypoint_choices[entrypoint] -%}
+  #### Choices for {{ path | join(" > ") }}
+
+  |Choice|
+  |---|
+  {%- for item in choices %}
+  | {{ item }} |
+  {%- endfor %}
+
+  {% endfor -%}
+  {% endif -%}
+  {% else -%}
+
+  This entrypoint has no options.
+
+  {% endfor -%}
+
+  ## Dependencies
+
+  {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
+  {%- for dependency in metadata.dependencies %}
+  {%- if dependency.src %}
+  - [{{ dependency.role }}]({{ dependency.src }})
+  {%- else %}
+  - {{ dependency.role }}
+  {%- endif %}
+    {%- if dependency.when %}
+    - **Condition**: `{{ dependency.when }}`
+    {%- endif %}
+  {%- endfor %}
+  {%- else %}
+  None.
+  {%- endif %}
+
+  ## Installation
+  Add this role to the requirements.yml of your playbook as follows:
+  ```yaml
+  roles:
+    - name: {{ role }}
+      src: https://github.com/punktDe/$role_name
+  ```
+
+  Afterwards, install the role by running `ansible-galaxy install -r requirements.yml`
+
+  ## Example Playbook
+
+  ```yaml
+  - hosts: all
+    roles:
+      - name: $role_name_short
+  ```
+
+  <!-- END_ANSIBLE_DOCS -->

proserver_init/templates/infra_role/generic/.github/workflows/generate_readme.yml

@@ -0,0 +1,49 @@
+---
+name: Generate README.md for the role
+
+on:
+  push:
+    branches:
+      - '**'
+    tags-ignore:
+      - '**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  readme:
+    name: Generate README.md from argument specs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: |
+          uv -q venv --allow-existing --seed .venv
+          . .venv/bin/activate
+          uv -q pip install -r requirements.txt
+
+      - name: Run aar-doc
+        run: |
+          . .venv/bin/activate
+          aar-doc --output-mode replace --config-file .aar-doc.yml . markdown
+
+      - name: Output diff
+        run: git diff README.md
+
+      - name: Commit and push README
+        run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add README.md
+          git diff-index --quiet HEAD || git commit -m "chore: Generate README.md"
+          git push

proserver_init/templates/infra_role/generic/README.md.template

@@ -0,0 +1,9 @@
+---
+galaxy_info:
+  author: "punkt.de"
+  license: "MIT"
+  role_name: $role_name_short
+  description: "$role_name_short role for Proserver"
+  namespace: "punktde"
+  min_ansible_version: "2.15"
+  platforms: []

proserver_init/templates/infra_role/generic/meta/main.yml.template

@@ -5,6 +5,6 @@
     GITHUB_ACTIONS: "maybe"
     ANSIBLE_HASH_BEHAVIOUR: merge
   tasks:
-    - name: "Include {{ role_name }}"
+    - name: "Include $role_name"
       ansible.builtin.include_role:
-        name: "{{ role_name }}"
+        name: "$role_name"

proserver_init/templates/infra_role/generic/molecule/default/converge.yml.template

@@ -5,3 +5,4 @@ molecule<25.2.0
 molecule-plugins
 yamllint
 requests
+aar-doc