[experimental] generate wiki docs from action/workflow YAML (#21)

* add some ansible to generate MD from actions/workflows

* overridable workflow/action output dirs

* workflow to generate and push wiki docs

* add pr trigger for testing

* remove workflow_dispatch

* fix wiki path use

* add a .gitignore

* fix wiki path

* typo

* testings

* fix path ending

* removed PR testing stuff

Author: briantist

.github/workflows/generate-wiki-docs.yml

@@ -0,0 +1,49 @@
+---
+name: Generate Wiki Docs
+on:
+  push:
+    branches: [main]
+    paths:
+      - .github/workflows/_shared*
+      - .github/workflows/generate-wiki-docs.yml
+      - actions/**/action.yml
+
+jobs:
+  generate:
+    env:
+      # this path is going to be used with rsync, it MUST end in a forward slash [/]
+      WIKI: ${{ github.workspace }}/wiki/
+      ANSIBLE_COLLECTIONS_PATHS: ${{ github.workspace }}/.internal/ansible
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Checkout wiki
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ github.repository }}.wiki
+          path: ${{ env.WIKI }}
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+
+      - name: Install Ansible
+        run: pip install 'ansible-core>=2.12,<2.13' --disable-pip-version-check
+
+      - name: Generate new docs
+        run: >-
+          ansible-playbook
+          internal.gha_docs.generate_docs
+          -e "action_output_dir=$WIKI/actions"
+          -e "workflow_output_dir=$WIKI/workflows"
+
+      - name: Publish docs
+        # @v2 https://github.com/Andrew-Chen-Wang/github-wiki-action/releases/tag/v2
+        uses: Andrew-Chen-Wang/github-wiki-action@b386aca0ddc5ec22b6003ba4cb50fa0b17243f6c
+        env:  # this action is written such that the inputs must be specified as env vars
+          WIKI_DIR: ${{ env.WIKI }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_MAIL: ${{ github.event.head_commit.author.email }}
+          GH_NAME: ${{ github.event.head_commit.author.name }}[bot]
+          WIKI_PUSH_MESSAGE: 'Docs for ${{ github.repository }}/${{ github.event.head_commit.id }} : ${{ github.event.head_commit.message }}'

.gitignore

@@ -0,0 +1,3 @@
+.vscode
+.test/simple-build/build
+wiki/

.internal/ansible/ansible_collections/internal/gha_docs/README.md

@@ -0,0 +1,3 @@
+## `internal.gha_docs`
+
+An internal collection for generating markdown docs from the actions and shared workflows in this repo.

.internal/ansible/ansible_collections/internal/gha_docs/galaxy.yml

@@ -0,0 +1,8 @@
+---
+namespace: internal
+name: gha_docs
+description: A collection internal to this repository for generating documentation from GHA content.
+version: 0.1.0
+readme: README.md
+authors:
+  - Brian Scholer (@briantist)

.internal/ansible/ansible_collections/internal/gha_docs/meta/runtime.yml

@@ -0,0 +1,2 @@
+---
+requires_ansible: '>=2.11,<2.13'

.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml

@@ -0,0 +1,46 @@
+---
+- hosts: localhost
+  gather_facts: false
+  vars:
+    # <root>/.internal/ansible/ansible_collections/internal/gha_docs/playbooks
+    # ^6     ^5        ^4      ^3                  ^2       ^1       ^ playbook_dir
+    repo_root: >-
+      {{
+        playbook_dir
+        | dirname
+        | dirname
+        | dirname
+        | dirname
+        | dirname
+        | dirname
+      }}
+    actions_root: '{{ repo_root }}/actions'
+    workflows_root: '{{ repo_root }}/.github/workflows'
+    output_root: '{{ role_path }}/files/output'
+    action_output_dir: '{{ output_root }}'
+    workflow_output_dir: '{{ output_root }}'
+  tasks:
+    - name: Find actions
+      ansible.builtin.find:
+        paths: '{{ actions_root }}'
+        recurse: true
+        patterns: action.yml
+      register: actions
+
+    - name: Generate actions docs
+      ansible.builtin.include_role:
+        name: internal.gha_docs.generate
+      vars:
+        type: action
+        file: '{{ item.path }}'
+        output: '{{ action_output_dir }}/action_{{ item.path | dirname | basename }}.md'
+      loop: '{{ actions.files }}'
+
+    - name: Generate workflow docs
+      ansible.builtin.include_role:
+        name: internal.gha_docs.generate
+      vars:
+        type: workflow
+        file: '{{ item }}'
+        output: '{{ workflow_output_dir }}/workflow{{ item | basename | splitext | first }}.md'
+      with_fileglob: '{{ workflows_root }}/_shared-*.yml'

.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/files/output/.gitignore

@@ -0,0 +1,2 @@
+**
+!.gitignore

.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/meta/argument_specs.yml

@@ -0,0 +1,21 @@
+---
+argument_specs:
+  main:
+    options:
+      file:
+        type: path
+        required: true
+        description: The path to the action or workflow file to parse.
+
+      type:
+        type: str
+        required: true
+        description: The type of input file.
+        choices:
+          - action
+          - workflow
+
+      output:
+        type: path
+        required: true
+        description: The path to the output file.

.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/tasks/main.yml

@@ -0,0 +1,34 @@
+---
+- name: Load the file
+  set_fact:
+    _src: "{{ lookup('ansible.builtin.file', file) | from_yaml }}"
+
+- name: Template the workflow docs
+  when: type == 'workflow'
+  vars:
+    full: '{{ _src }}'
+    name: '{{ _src.name }}'
+    reference: '{{ file | basename }}'
+    jobs: '{{ _src.jobs }}'
+    inputs: '{{ _src[true].workflow_call.inputs | default({}) }}'
+    outputs: '{{ _src[true].workflow_call.outputs | default({}) }}'
+  ansible.builtin.template:
+    src: workflow.md.j2
+    dest: '{{ output }}'
+    force: true
+    mode: '644'
+
+- name: Template the action docs
+  when: type == 'action'
+  vars:
+    full: '{{ _src }}'
+    name: '{{ _src.name }}'
+    reference: '{{ file | dirname | basename }}'
+    description: '{{ _src.description }}'
+    inputs: '{{ _src.inputs | default({}) }}'
+    outputs: '{{ _src.outputs | default({}) }}'
+  ansible.builtin.template:
+    src: action.md.j2
+    dest: '{{ output }}'
+    force: true
+    mode: '644'

.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/action.md.j2

@@ -0,0 +1,20 @@
+# `{{ reference }}`
+## {{ name }}
+
+{{ description }}
+
+### Inputs
+| Name (✅required) | Default | Description |
+| ----------------- | ------- | ----------- |
+{% for name, inp in inputs.items() %}
+| `{{ name }}`{% if inp.required %}✅{% endif %} | {% if inp.default is defined %}{% if "\n" in inp.default %}✳ _see `action.yml` for full default value_{% else %}<code>{{ inp.default.replace('`', '\`') }}</code>{% endif %}{% endif %} | {{ (inp.description.replace("\n", '<br />')) }} |
+{% endfor %}
+
+<hr />
+
+### Outputs
+| Name | Description |
+| ---- | ----------- |
+{% for name, out in outputs.items() %}
+| `{{ name }}` | {{ (out.description | default('')).replace("\n", '<br />') }} |
+{% endfor %}