From 323bec567678efbb673934eef62c231a2f9f6700 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Sun, 16 Jan 2022 14:05:26 -0500
Subject: [PATCH 1/5] add some ansible to generate MD from actions/workflows

---
 .../internal/gha_docs/README.md               |  3 ++
 .../internal/gha_docs/galaxy.yml              |  8 ++++
 .../internal/gha_docs/meta/runtime.yml        |  2 +
 .../gha_docs/playbooks/generate_docs.yml      | 44 +++++++++++++++++++
 .../roles/generate/files/output/.gitignore    |  2 +
 .../roles/generate/meta/argument_specs.yml    | 21 +++++++++
 .../gha_docs/roles/generate/tasks/main.yml    | 34 ++++++++++++++
 .../roles/generate/templates/action.md.j2     | 20 +++++++++
 .../roles/generate/templates/workflow.md.j2   | 27 ++++++++++++
 9 files changed, 161 insertions(+)
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/README.md
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/galaxy.yml
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/meta/runtime.yml
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/roles/generate/files/output/.gitignore
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/roles/generate/meta/argument_specs.yml
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/roles/generate/tasks/main.yml
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/action.md.j2
 create mode 100644 .internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/workflow.md.j2

diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/README.md b/.internal/ansible/ansible_collections/internal/gha_docs/README.md
new file mode 100644
index 0000000..4cb20bf
--- /dev/null
+++ b/.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.
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/galaxy.yml b/.internal/ansible/ansible_collections/internal/gha_docs/galaxy.yml
new file mode 100644
index 0000000..66776e0
--- /dev/null
+++ b/.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)
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/meta/runtime.yml b/.internal/ansible/ansible_collections/internal/gha_docs/meta/runtime.yml
new file mode 100644
index 0000000..3b8a2bb
--- /dev/null
+++ b/.internal/ansible/ansible_collections/internal/gha_docs/meta/runtime.yml
@@ -0,0 +1,2 @@
+---
+requires_ansible: '>=2.11,<2.13'
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml b/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml
new file mode 100644
index 0000000..6af35e2
--- /dev/null
+++ b/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml
@@ -0,0 +1,44 @@
+---
+- 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_dir: '{{ role_path }}/files/output'
+  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: '{{ 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: '{{ output_dir }}/workflow{{ item | basename | splitext | first }}.md'
+      with_fileglob: '{{ workflows_root }}/_shared-*.yml'
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/files/output/.gitignore b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/files/output/.gitignore
new file mode 100644
index 0000000..1287e9b
--- /dev/null
+++ b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/files/output/.gitignore
@@ -0,0 +1,2 @@
+**
+!.gitignore
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/meta/argument_specs.yml b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/meta/argument_specs.yml
new file mode 100644
index 0000000..a77651b
--- /dev/null
+++ b/.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.
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/tasks/main.yml b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/tasks/main.yml
new file mode 100644
index 0000000..45c892c
--- /dev/null
+++ b/.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'
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/action.md.j2 b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/action.md.j2
new file mode 100644
index 0000000..9493a03
--- /dev/null
+++ b/.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 %}
diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/workflow.md.j2 b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/workflow.md.j2
new file mode 100644
index 0000000..f715e37
--- /dev/null
+++ b/.internal/ansible/ansible_collections/internal/gha_docs/roles/generate/templates/workflow.md.j2
@@ -0,0 +1,27 @@
+# `{{ reference }}`
+## {{ name }}
+
+### Jobs
+| ID  | Name | Permissions |
+| --- | ---- | ----------- |
+{% for id, job in jobs.items() %}
+| `{{ id }}` | {{ job.name | default(id) }} | {% if job.permissions is not defined %}_default_{% else %}<ul>{% for resource, access in job.permissions.items() %}<li><strong>{{ resource }}</strong>: <code>{{ access }}</code></li>{% endfor %}{% endif %} |
+{% endfor %}
+
+<hr />
+
+### Inputs
+| Name (✅required) | Type | Default | Description |
+| ----------------- | ---- | ------- | ----------- |
+{% for name, inp in inputs.items() %}
+| `{{ name }}`{% if inp.required %}✅{% endif %} | {{ inp.type }} | {% if inp.default is defined %}{% if "\n" in inp.default | string %}✳ _see `action.yml` for full default value_{% else %}<code>{{ (inp.default | string).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 %}

From c342593663815fd8802b214bbd2fd1bc211f3baa Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Sun, 16 Jan 2022 15:56:17 -0500
Subject: [PATCH 2/5] overridable workflow/action output dirs

---
 .../internal/gha_docs/playbooks/generate_docs.yml         | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml b/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml
index 6af35e2..de6789a 100644
--- a/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml
+++ b/.internal/ansible/ansible_collections/internal/gha_docs/playbooks/generate_docs.yml
@@ -16,7 +16,9 @@
       }}
     actions_root: '{{ repo_root }}/actions'
     workflows_root: '{{ repo_root }}/.github/workflows'
-    output_dir: '{{ role_path }}/files/output'
+    output_root: '{{ role_path }}/files/output'
+    action_output_dir: '{{ output_root }}'
+    workflow_output_dir: '{{ output_root }}'
   tasks:
     - name: Find actions
       ansible.builtin.find:
@@ -31,7 +33,7 @@
       vars:
         type: action
         file: '{{ item.path }}'
-        output: '{{ output_dir }}/action_{{ item.path | dirname | basename }}.md'
+        output: '{{ action_output_dir }}/action_{{ item.path | dirname | basename }}.md'
       loop: '{{ actions.files }}'
 
     - name: Generate workflow docs
@@ -40,5 +42,5 @@
       vars:
         type: workflow
         file: '{{ item }}'
-        output: '{{ output_dir }}/workflow{{ item | basename | splitext | first }}.md'
+        output: '{{ workflow_output_dir }}/workflow{{ item | basename | splitext | first }}.md'
       with_fileglob: '{{ workflows_root }}/_shared-*.yml'

From e0161161d830e1fd0c09d2fd4d4c738ace672fbe Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Sun, 16 Jan 2022 16:52:14 -0500
Subject: [PATCH 3/5] workflow to generate and push wiki docs

---
 .github/workflows/generate-wiki-docs.yml | 49 ++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 .github/workflows/generate-wiki-docs.yml

diff --git a/.github/workflows/generate-wiki-docs.yml b/.github/workflows/generate-wiki-docs.yml
new file mode 100644
index 0000000..6039700
--- /dev/null
+++ b/.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
+  workflow_dispatch:
+
+jobs:
+  generate:
+    env:
+      WIKI: ${{ runner.temp }}/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.gh_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 }}'

From feff20ac756dc91e4c6f4757f34bf689875657c1 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Sun, 16 Jan 2022 16:53:52 -0500
Subject: [PATCH 4/5] add pr trigger for testing

---
 .github/workflows/generate-wiki-docs.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/generate-wiki-docs.yml b/.github/workflows/generate-wiki-docs.yml
index 6039700..b5114e3 100644
--- a/.github/workflows/generate-wiki-docs.yml
+++ b/.github/workflows/generate-wiki-docs.yml
@@ -1,6 +1,9 @@
 ---
 name: Generate Wiki Docs
 on:
+  pull_request: ######## TO BE REMOVED BEFORE MERGING
+    types: [opened, reopened, synchronize]
+
   push:
     branches: [main]
     paths:

From 6c90c5a3d4833c17c415bf86370ade9d94c53d66 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Sun, 16 Jan 2022 17:01:37 -0500
Subject: [PATCH 5/5] remove workflow_dispatch

---
 .github/workflows/generate-wiki-docs.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/generate-wiki-docs.yml b/.github/workflows/generate-wiki-docs.yml
index b5114e3..e1f7e67 100644
--- a/.github/workflows/generate-wiki-docs.yml
+++ b/.github/workflows/generate-wiki-docs.yml
@@ -10,7 +10,6 @@ on:
       - .github/workflows/_shared*
       - .github/workflows/generate-wiki-docs.yml
       - actions/**/action.yml
-  workflow_dispatch:
 
 jobs:
   generate: