docs: moving docs to pages (#3633)

The documentation in our README have become quite extensive over the
years. This PR is moving docs including examples and modules to a
documentation site. The top-level readme is shrinked down to some basic
/ essential information.

- New top-level readme:
https://github.com/philips-labs/terraform-aws-github-runner/tree/npalm/mkdocs?tab=readme-ov-file
- Documentation site:
https://philips-labs.github.io/terraform-aws-github-runner

For examples and module documentation sources in example and module
directories are linked.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: npalm

.ci/terraform-init-all.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+# This script will run terraform init in all subdirectories of the examples directory
+# required to run tflint via pre-commit
+
+# only run the script if a uniique pid file exits if not creat it or --force flag is passed
+pid="/tmp/philips-labs-terraform-aws-github-runner.pid"
+if [ "$1" == "--force" ]; then
+  rm -f /tmp/philips-labs-terraform-aws-github-runner.pid
+fi
+
+if [ ! -f $pid ]; then
+  echo $$ > $pid
+else
+  echo "Init all terraform directories will be skipped. To run the script remove the file $pid or run with --force"
+  exit 0
+fi
+
+# Change to the examples directory
+example_dirs=$(find examples -mindepth 1 -maxdepth 2 -type d | grep -v "templates")
+module_dirs=$(find modules -mindepth 1 -maxdepth 2 -type d | grep -v "templates")
+
+# merge example_dirs and module_dirs in terraform_dirs
+terraform_dirs=$(echo $example_dirs $module_dirs "modules/runners/pool" | tr " " "\n" | sort -u | tr "\n" " ")
+
+for dir in $terraform_dirs; do
+  # Check if the subdirectory exists in Git
+  if git rev-parse --is-inside-work-tree &>/dev/null && git ls-files --error-unmatch "$dir" &>/dev/null; then
+    echo "Running terraform init in ${dir} - supressing output"
+    pushd "$dir" >/dev/null
+    terraform init -lockfile=readonly -backend=false &>/dev/null || true
+    popd >/dev/null
+  fi
+done

.github/workflows/update-docs.yml

@@ -32,9 +32,32 @@ jobs:
         uses: peter-evans/create-pull-request@153407881ec5c347639a548ade7d8ad1d6740e38 # ratchet:peter-evans/[email protected]
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: "Update Terraform docs"
+          commit-message: "docs: auto update terraform docs"
           title: "docs: Update Terraform docs"
           branch: update-docs
           branch-suffix: random
           base: ${{ github.event.pull_request.base.ref }}
           delete-branch: true
+
+  deploy-pages:
+    needs: [docs]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # ratchet:actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-material-extensions
+      - run: mkdocs gh-deploy --force -c -b gh-pages

.gitignore

@@ -22,3 +22,4 @@ secrets.auto.tfvars
 **/coverage/*
 
 node_modules/
+site/

README.md

@@ -0,0 +1 @@
+--8<-- "images/README.md"