From 170ce5f57c236c33d4a78c67c8abba057617acac Mon Sep 17 00:00:00 2001
From: Greg Harvey <greg.harvey@gmail.com>
Date: Tue, 7 Jan 2025 17:00:01 +0100
Subject: [PATCH 1/5] Fixing docs publishing.

---
 .github/workflows/ce-deploy-publish-docs.yml | 84 ++++++++++----------
 contribute/toc.sh                            |  4 +-
 2 files changed, 46 insertions(+), 42 deletions(-)

diff --git a/.github/workflows/ce-deploy-publish-docs.yml b/.github/workflows/ce-deploy-publish-docs.yml
index 45148600..df31e516 100644
--- a/.github/workflows/ce-deploy-publish-docs.yml
+++ b/.github/workflows/ce-deploy-publish-docs.yml
@@ -1,11 +1,12 @@
 name: Publish documentation
 
-# Run this workflow every time a new commit pushed to your repository
+# Run this workflow on demand or every time a PR is accepted to a main branch
 on:
   pull_request:
     types: [closed]
     branches:
       - 1.x
+  workflow_dispatch:
 
 jobs:
   # Set the job key. The key is displayed as the job name
@@ -14,51 +15,54 @@ jobs:
     # Name the Job
     name: Publish ce-deploy documentation
     # Set the type of machine to run on
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
+
+    # Use our ce-dev Debian base container
+    container:
+      image: codeenigma/ce-dev-controller:2.x
+      volumes:
+        - ${{ github.workspace }}:/home/controller
 
     steps:
-      # Checks out a copy of your repository on the ubuntu-latest machine
-      - name: Checkout code
-        uses: actions/checkout@v2
+      - name: Install wiki2pages
+        run: /usr/bin/su - ce-dev -c "/usr/bin/git clone https://github.com/codeenigma/wikis2pages.git /home/ce-dev/build/wiki2pages"
+
+      - name: Update local applications
+        run: |
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/ce-provision && /usr/bin/git pull origin 2.x"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/ce-deploy && /usr/bin/git pull origin 1.x"
 
-      # Configures global Git variables for committing
-      - name: Configure Git
+      - name: Set up Ansible hosts file
         run: |
-          git config --global user.email "sysadm@codeenigma.com"
-          git config --global user.name "Code Enigma CI"
+          mkdir -p /home/ce-dev/ansible/bin/hosts
+          echo "wikis2pages-hugo ansible_host=127.0.0.1" > /home/ce-dev/ansible/bin/hosts/hosts
 
-      # Installs the ce-dev stack
-      - name: Install ce-dev
+      - name: Set up SSH config
         run: |
-          cd /tmp
-          wget https://golang.org/dl/go1.16.3.linux-amd64.tar.gz
-          sudo tar -C /usr/local -xzf go1.16.3.linux-amd64.tar.gz
-          export PATH=$PATH:/usr/local/go/bin
-          git clone https://github.com/FiloSottile/mkcert && cd mkcert
-          go build -ldflags "-X main.Version=$(git describe --tags)"
-          sudo mv ./mkcert /usr/local/bin && cd ../
-          sudo chmod +x /usr/local/bin/mkcert
-          rm -Rf mkcert
-          curl -sL https://raw.githubusercontent.com/codeenigma/ce-dev/1.x/install.sh | /bin/sh -s -- linux
+          echo "StrictHostKeyChecking=no" > /home/ce-dev/.ssh/config
+          cat /home/ce-dev/.ssh/id_rsa.pub > /home/ce-dev/.ssh/authorized_keys
+          chown ce-dev:ce-dev /home/ce-dev/.ssh/config
+          chmod 700 /home/ce-dev/.ssh/config
+          chown ce-dev:ce-dev /home/ce-dev/.ssh/authorized_keys
+          chmod 700 /home/ce-dev/.ssh/authorized_keys
+
+      - name: Start SSHD
+        run: /usr/sbin/sshd&
 
-      # Builds the table of contents for the docs
-      - name: Documentation (build table of contents)
-        if: ${{ github.event.pull_request.base.ref == '1.x' }}
-        run: contribute/toc.sh
-        shell: bash
+      - name: Initialise wiki2pages for ce-deploy ${{ github.event.pull_request.base.ref }}
+        run: |
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /bin/sh init.sh --repo https://github.com/codeenigma/ce-deploy.git --branch ${{ github.event.pull_request.base.ref }} --no-ce-dev"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /home/ce-dev/ansible/bin/ansible-playbook -e 'wiki2pages_build_path=/home/ce-dev/build/wiki2pages' -i /home/ce-dev/ansible/bin/hosts /home/ce-dev/build/wiki2pages/ce-dev/ansible/provision.yml"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /bin/sh set-current.sh --project ce-deploy-${{ github.event.pull_request.base.ref }} --no-ce-dev"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /home/ce-dev/ansible/bin/ansible-playbook -e 'wiki2pages_build_path=/home/ce-dev/build/wiki2pages launch_hugo_server=false' -i /home/ce-dev/ansible/bin/hosts /home/ce-dev/build/wiki2pages/ce-dev/ansible/deploy.yml"
+
+      - name: Run Hugo
+        run: |
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && hugo"
+          ls -la /home/ce-dev/build/wiki2pages/public/ce-deploy-${{ github.event.pull_request.base.ref }}/
 
-      # Uses the ce-dev stack to run Hugo to build and deploy the docs
-      - name: Documentation (build and publish)
-        if: ${{ github.event.pull_request.base.ref == '1.x' }}
+      - name: Publish documentation
         run: |
-          cd
-          git clone https://github.com/codeenigma/wikis2pages.git
-          cd wikis2pages
-          /bin/bash init.sh https://${{ secrets.GITHUB_TOKEN }}@github.com/codeenigma/ce-deploy.git 1.x
-          /bin/sh set-current.sh ce-deploy-1.x-travis
-          docker exec --user ce-dev --workdir /home/ce-dev/deploy/live.local wikis2pages-hugo hugo
-          /bin/sh .github-actions-push.sh
-          cd /home/runner/wikis2pages/public/ce-deploy-1.x-travis
-          git remote add ci https://${{ secrets.DOCS_GITHUB_TOKEN }}@github.com/codeenigma/ce-deploy-docs.git
-          git push ci master
-        shell: bash
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /bin/sh /home/ce-dev/build/wiki2pages/.github-actions-push.sh"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages/public/ce-deploy-${{ github.event.pull_request.base.ref }} && /usr/bin/git remote add ci https://${{ secrets.DOCS_GITHUB_TOKEN }}@github.com/codeenigma/ce-deploy-docs.git"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages/public/ce-deploy-${{ github.event.pull_request.base.ref }} && /usr/bin/git push ci master"
diff --git a/contribute/toc.sh b/contribute/toc.sh
index face006c..8dc9a1c8 100755
--- a/contribute/toc.sh
+++ b/contribute/toc.sh
@@ -114,7 +114,7 @@ parse_roles_toc(){
       "# "*)
         if [ "$WRITE" = "true" ]; then
           TITLE=$(echo "$LINE" | cut -c 3-)
-          echo "$INDENT"" - [$TITLE](/$RELATIVE)" >> "$TMP_SIDEBAR"
+          echo "$INDENT"" - [$TITLE]($RELATIVE)" >> "$TMP_SIDEBAR"
           WRITE="false"
         fi
       ;;
@@ -137,4 +137,4 @@ generate_roles_toc
 
 cp_single_page install
 cp_single_page contribute
-cp_single_page scripts
\ No newline at end of file
+cp_single_page scripts

From d21c717d4d3c64c61973e98d6c0d9933353fe4c3 Mon Sep 17 00:00:00 2001
From: Greg Harvey <greg.harvey@gmail.com>
Date: Tue, 7 Jan 2025 17:01:05 +0100
Subject: [PATCH 2/5] Updating docs.

---
 docs/_Sidebar.md                             | 95 ++++++++++----------
 docs/roles/cache_clear/cache_clear-mautic.md |  7 --
 2 files changed, 47 insertions(+), 55 deletions(-)
 delete mode 100644 docs/roles/cache_clear/cache_clear-mautic.md

diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
index b1f28b08..a50bee09 100644
--- a/docs/_Sidebar.md
+++ b/docs/_Sidebar.md
@@ -1,50 +1,49 @@
 &nbsp;
-- [Home](/)
-  - [Install](/install)
-  - [Usage](/scripts)
+- [Home]()
+  - [Install](install)
+  - [Usage](scripts)
   - [Roles](roles)
-     - [API call](/roles/api_call)
-     - [Config](/roles/cache_clear)
-       - [Drupal 7](/roles/cache_clear/cache_clear-drupal7)
-       - [Drupal 8](/roles/cache_clear/cache_clear-drupal8)
-       - [Matomo](/roles/cache_clear/cache_clear-matomo)
-       - [Drupal 8](/roles/cache_clear/cache_clear-mautic)
-       - [Opcache](/roles/cache_clear/cache_clear-opcache)
-       - [Symfony](/roles/cache_clear/cache_clear-symfony)
-     - [ce-dev](/roles/ce_dev)
-       - [ce-dev prebuild](/roles/ce_dev/ce_dev_prebuild)
-     - [CLI Tools](/roles/cli)
-       - [Drush](/roles/cli/cachetool)
-       - [Drush](/roles/cli/drush)
-     - [Composer](/roles/composer)
-     - [Config](/roles/config_generate)
-       - [Drupal 7](/roles/config_generate/config_generate-drupal7)
-       - [Drupal 8](/roles/config_generate/config_generate-drupal8)
-       - [Drupal 8](/roles/config_generate/config_generate-matomo)
-       - [Mautic](/roles/config_generate/config_generate-mautic)
-     - [Cron](/roles/cron)
-       - [Database backup cron task](/roles/cron/cron_database_backup)
-         - [Database backup cron task - MySQL](/roles/cron/cron_database_backup/cron_database_backup-mysql)
-       - [Drupal 7 cron](/roles/cron/cron_drupal7)
-       - [Drupal 8 cron](/roles/cron/cron_drupal8)
-       - [Database backup cron task - MySQL](/roles/cron/cron_matomo)
-       - [Mautic cron tasks](/roles/cron/cron_mautic)
-     - [Data backups](/roles/database_backup)
-       - [MySQL backups](/roles/database_backup/database_backup-mysql)
-     - [Deploy](/roles/deploy_code)
-     - [Deploy container](/roles/deploy_container)
-     - [Exit](/roles/_exit)
-     - [Init](/roles/_init)
-     - [LHCI run](/roles/lhci_run)
-     - [Maintenance Mode](/roles/maintenance_mode)
-     - ["Meta"](/roles/_meta)
-       - [Drupal 10](/roles/_meta/deploy-drupal10)
-       - [Drupal 7](/roles/_meta/deploy-drupal7)
-       - [Drupal 8](/roles/_meta/deploy-drupal8)
-       - [Matomo](/roles/_meta/deploy-matomo)
-       - [Mautic](/roles/_meta/deploy-mautic)
-       - [SimpleSAMLphp](/roles/_meta/deploy-simplesamlphp)
-     - [NPM](/roles/npm)
-     - [Sync roles](/roles/sync)
-       - [Database sync](/roles/sync/database_sync)
-         - [Database sync - MySQL](/roles/sync/database_sync/database_sync-mysql)
+     - [API call](roles/api_call)
+     - [Config](roles/cache_clear)
+       - [Drupal 7](roles/cache_clear/cache_clear-drupal7)
+       - [Drupal 8](roles/cache_clear/cache_clear-drupal8)
+       - [Matomo](roles/cache_clear/cache_clear-matomo)
+       - [Opcache](roles/cache_clear/cache_clear-opcache)
+       - [Symfony](roles/cache_clear/cache_clear-symfony)
+     - [ce-dev](roles/ce_dev)
+       - [ce-dev prebuild](roles/ce_dev/ce_dev_prebuild)
+     - [CLI Tools](roles/cli)
+       - [Drush](roles/cli/cachetool)
+       - [Drush](roles/cli/drush)
+     - [Composer](roles/composer)
+     - [Config](roles/config_generate)
+       - [Drupal 7](roles/config_generate/config_generate-drupal7)
+       - [Drupal 8](roles/config_generate/config_generate-drupal8)
+       - [Drupal 8](roles/config_generate/config_generate-matomo)
+       - [Mautic](roles/config_generate/config_generate-mautic)
+     - [Cron](roles/cron)
+       - [Database backup cron task](roles/cron/cron_database_backup)
+         - [Database backup cron task - MySQL](roles/cron/cron_database_backup/cron_database_backup-mysql)
+       - [Drupal 7 cron](roles/cron/cron_drupal7)
+       - [Drupal 8 cron](roles/cron/cron_drupal8)
+       - [Database backup cron task - MySQL](roles/cron/cron_matomo)
+       - [Mautic cron tasks](roles/cron/cron_mautic)
+     - [Data backups](roles/database_backup)
+       - [MySQL backups](roles/database_backup/database_backup-mysql)
+     - [Deploy](roles/deploy_code)
+     - [Deploy container](roles/deploy_container)
+     - [Exit](roles/_exit)
+     - [Init](roles/_init)
+     - [LHCI run](roles/lhci_run)
+     - [Maintenance Mode](roles/maintenance_mode)
+     - ["Meta"](roles/_meta)
+       - [Drupal 10](roles/_meta/deploy-drupal10)
+       - [Drupal 7](roles/_meta/deploy-drupal7)
+       - [Drupal 8](roles/_meta/deploy-drupal8)
+       - [Matomo](roles/_meta/deploy-matomo)
+       - [Mautic](roles/_meta/deploy-mautic)
+       - [SimpleSAMLphp](roles/_meta/deploy-simplesamlphp)
+     - [NPM](roles/npm)
+     - [Sync roles](roles/sync)
+       - [Database sync](roles/sync/database_sync)
+         - [Database sync - MySQL](roles/sync/database_sync/database_sync-mysql)
diff --git a/docs/roles/cache_clear/cache_clear-mautic.md b/docs/roles/cache_clear/cache_clear-mautic.md
deleted file mode 100644
index 16360291..00000000
--- a/docs/roles/cache_clear/cache_clear-mautic.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Drupal 8
-Clear caches for Drupal 8.
-<!--TOC-->
-<!--ENDTOC-->
-
-<!--ROLEVARS-->
-<!--ENDROLEVARS-->

From f778ec27e767df4c82d1f06600c719d6735c20ca Mon Sep 17 00:00:00 2001
From: Greg Harvey <greg.harvey@gmail.com>
Date: Tue, 7 Jan 2025 17:11:52 +0100
Subject: [PATCH 3/5] Updating name of job.

---
 .wikis2pages.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.wikis2pages.yml b/.wikis2pages.yml
index 5addb318..a282ce2d 100644
--- a/.wikis2pages.yml
+++ b/.wikis2pages.yml
@@ -1,4 +1,4 @@
-ce-deploy-1.x-travis:
+ce-deploy-1.x:
   src: https://github.com/codeenigma/ce-deploy.git
   src_branch: 1.x
   src_subdir: 'docs'
@@ -7,4 +7,4 @@ ce-deploy-1.x-travis:
   dest_subdir: 1.x
   title: ce-deploy
   type: doc
-  base_url: https://codeenigma.github.io/ce-deploy-docs/1.x
\ No newline at end of file
+  base_url: https://codeenigma.github.io/ce-deploy-docs/1.x

From 65bfbca52d3bcaa3bd9d41ea87127b74f0c5236e Mon Sep 17 00:00:00 2001
From: Greg Harvey <greg.harvey@gmail.com>
Date: Wed, 8 Jan 2025 13:02:59 +0100
Subject: [PATCH 4/5] Making docs publishing changes from ce-provision in
 ce-deploy.

---
 .github/workflows/ce-deploy-publish-docs.yml |  43 ++++--
 contribute/toc.sh                            |   2 +-
 contribute/toc_hugo.sh                       | 140 +++++++++++++++++++
 3 files changed, 173 insertions(+), 12 deletions(-)
 create mode 100755 contribute/toc_hugo.sh

diff --git a/.github/workflows/ce-deploy-publish-docs.yml b/.github/workflows/ce-deploy-publish-docs.yml
index df31e516..063ef344 100644
--- a/.github/workflows/ce-deploy-publish-docs.yml
+++ b/.github/workflows/ce-deploy-publish-docs.yml
@@ -12,6 +12,8 @@ jobs:
   # Set the job key. The key is displayed as the job name
   # when a job name is not provided
   publish-docs:
+    # Only run the job if it is not coming from a documentation branch
+    if: ${{ github.event.pull_request.head.ref != 'docs-${{ github.event.pull_request.base.ref }}' }}
     # Name the Job
     name: Publish ce-deploy documentation
     # Set the type of machine to run on
@@ -24,30 +26,49 @@ jobs:
         - ${{ github.workspace }}:/home/controller
 
     steps:
-      - name: Install wiki2pages
-        run: /usr/bin/su - ce-dev -c "/usr/bin/git clone https://github.com/codeenigma/wikis2pages.git /home/ce-dev/build/wiki2pages"
+      - uses: actions/checkout@v4
+        with:
+          ref: docs-${{ github.event.pull_request.base.ref }}
 
-      - name: Update local applications
+      # Configure environment
+      - name: Prepare Git, GitHub CLI and installed CE tools
         run: |
+          /usr/bin/git config --global user.email "sysadm@codeenigma.com"
+          /usr/bin/git config --global user.name "Code Enigma CI"
+          /usr/bin/git config --global pull.rebase false
+          /usr/bin/git config --global --add safe.directory /__w/ce-deploy/ce-deploy
+          (type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) && sudo mkdir -p -m 755 /etc/apt/keyrings && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null && sudo apt update && sudo apt install gh -y
           /usr/bin/su - ce-dev -c "cd /home/ce-dev/ce-provision && /usr/bin/git pull origin 2.x"
           /usr/bin/su - ce-dev -c "cd /home/ce-dev/ce-deploy && /usr/bin/git pull origin 1.x"
 
-      - name: Set up Ansible hosts file
+      # First build and publish the markdown docs
+      - name: Build and commit table of contents and README files back to the repo
         run: |
-          mkdir -p /home/ce-dev/ansible/bin/hosts
-          echo "wikis2pages-hugo ansible_host=127.0.0.1" > /home/ce-dev/ansible/bin/hosts/hosts
+          /bin/sh contribute/toc.sh
+          /usr/bin/find . -name "*.md" | xargs git add
+          /usr/bin/git diff --quiet && git diff --staged --quiet || git commit -am "GitHub Actions - updating markdown docs - ${{ steps.date.outputs.date }}"
+          /usr/bin/git push
+
+      # Create docs pull request
+      - name: Create a documentation pull request
+        run: gh pr create --base ${{ github.event.pull_request.base.ref }} --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update" --body "**Automated pull request** created by GitHub Actions because of a documentation update."
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Set up SSH config
+      - name: Install wiki2pages
+        run: /usr/bin/su - ce-dev -c "/usr/bin/git clone https://github.com/codeenigma/wikis2pages.git /home/ce-dev/build/wiki2pages"
+
+      - name: Set up Ansible and SSH
         run: |
+          mkdir -p /home/ce-dev/ansible/bin/hosts
+          echo "wikis2pages-hugo ansible_host=127.0.0.1" > /home/ce-dev/ansible/bin/hosts/hosts
           echo "StrictHostKeyChecking=no" > /home/ce-dev/.ssh/config
           cat /home/ce-dev/.ssh/id_rsa.pub > /home/ce-dev/.ssh/authorized_keys
           chown ce-dev:ce-dev /home/ce-dev/.ssh/config
           chmod 700 /home/ce-dev/.ssh/config
           chown ce-dev:ce-dev /home/ce-dev/.ssh/authorized_keys
           chmod 700 /home/ce-dev/.ssh/authorized_keys
-
-      - name: Start SSHD
-        run: /usr/sbin/sshd&
+          /usr/sbin/sshd&
 
       - name: Initialise wiki2pages for ce-deploy ${{ github.event.pull_request.base.ref }}
         run: |
@@ -55,11 +76,11 @@ jobs:
           /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /home/ce-dev/ansible/bin/ansible-playbook -e 'wiki2pages_build_path=/home/ce-dev/build/wiki2pages' -i /home/ce-dev/ansible/bin/hosts /home/ce-dev/build/wiki2pages/ce-dev/ansible/provision.yml"
           /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /bin/sh set-current.sh --project ce-deploy-${{ github.event.pull_request.base.ref }} --no-ce-dev"
           /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && /home/ce-dev/ansible/bin/ansible-playbook -e 'wiki2pages_build_path=/home/ce-dev/build/wiki2pages launch_hugo_server=false' -i /home/ce-dev/ansible/bin/hosts /home/ce-dev/build/wiki2pages/ce-dev/ansible/deploy.yml"
+          /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages/content/ce-deploy-${{ github.event.pull_request.base.ref }} && /bin/sh contribute/toc_hugo.sh"
 
       - name: Run Hugo
         run: |
           /usr/bin/su - ce-dev -c "cd /home/ce-dev/build/wiki2pages && hugo"
-          ls -la /home/ce-dev/build/wiki2pages/public/ce-deploy-${{ github.event.pull_request.base.ref }}/
 
       - name: Publish documentation
         run: |
diff --git a/contribute/toc.sh b/contribute/toc.sh
index 8dc9a1c8..8c108c60 100755
--- a/contribute/toc.sh
+++ b/contribute/toc.sh
@@ -114,7 +114,7 @@ parse_roles_toc(){
       "# "*)
         if [ "$WRITE" = "true" ]; then
           TITLE=$(echo "$LINE" | cut -c 3-)
-          echo "$INDENT"" - [$TITLE]($RELATIVE)" >> "$TMP_SIDEBAR"
+          echo "$INDENT"" - [$TITLE](/$RELATIVE)" >> "$TMP_SIDEBAR"
           WRITE="false"
         fi
       ;;
diff --git a/contribute/toc_hugo.sh b/contribute/toc_hugo.sh
new file mode 100755
index 00000000..8dc9a1c8
--- /dev/null
+++ b/contribute/toc_hugo.sh
@@ -0,0 +1,140 @@
+#!/bin/sh
+# shellcheck disable=SC2094
+# shellcheck disable=SC2129
+IFS=$(printf '\n\t')
+set -e
+OWN_DIR=$(dirname "$0")
+cd "$OWN_DIR" || exit 1
+OWN_DIR=$(git rev-parse --show-toplevel)
+cd "$OWN_DIR" || exit 1
+OWN_DIR=$(pwd -P)
+
+# @param
+# $1 string filepath
+cp_role_page(){
+  RELATIVE=$(realpath --relative-to="$OWN_DIR" "$(dirname "$1")")
+  if [ ! -d "$OWN_DIR/docs/$RELATIVE" ]; then
+    mkdir -p "$OWN_DIR/docs/$RELATIVE"
+  fi
+  cp "$1" "$OWN_DIR/docs/$RELATIVE.md"
+}
+
+# @param
+# $1 string folder
+cp_single_page(){
+  if [ ! -d "$OWN_DIR/docs/$1" ]; then
+    mkdir "$OWN_DIR/docs/$1"
+  fi
+  cp "$OWN_DIR/$1/README.md" "$OWN_DIR/docs/$1.md"
+}
+
+# @param
+# $1 (string) filename
+parse_role_variables(){
+  TMP_MD=$(mktemp)
+  WRITE=1
+  # Ensure we have a trailing line.
+  echo "" >> "$1"
+  while read -r LINE; do
+    case $LINE in
+    '<!--ROLEVARS-->')
+      echo "$LINE" >> "$TMP_MD"
+      generate_role_variables "$1"
+      WRITE=0
+    ;;
+    '<!--ENDROLEVARS-->')
+      echo "$LINE" >> "$TMP_MD"
+      WRITE=1
+    ;;
+    '<!--TOC-->')
+      echo "$LINE" >> "$TMP_MD"
+      WRITE=0
+    ;;
+    '<!--ENDTOC-->')
+      echo "$LINE" >> "$TMP_MD"
+      WRITE=1
+    ;;
+    *)
+    if [ $WRITE = 1 ]; then
+      echo "$LINE" >> "$TMP_MD"
+    fi
+    ;;
+    esac
+  done < "$1"
+  printf '%s\n' "$(cat "$TMP_MD")" > "$1"
+  rm "$TMP_MD"
+}
+
+# @param
+# $1 (string) filename
+generate_role_variables(){
+  VAR_FILE="$(dirname "$1")/defaults/main.yml"
+  if [ -f "$VAR_FILE" ]; then
+    echo "## Default variables"  >> "$TMP_MD"
+    echo '```yaml' >> "$TMP_MD"
+    cat "$VAR_FILE" >> "$TMP_MD"
+    echo "" >> "$TMP_MD"
+    echo '```' >> "$TMP_MD"
+    echo "" >> "$TMP_MD"
+  fi
+}
+
+generate_roles_toc(){
+  TMP_SIDEBAR=$(mktemp)
+  WRITE="true"
+  while read -r LINE; do
+    case $LINE in
+    "  - [Roles](roles)")
+      echo "$LINE" >> "$TMP_SIDEBAR"
+      parse_roles_toc roles 2
+      WRITE="false"
+    ;;
+    "  -"*)
+      WRITE="true"
+      echo "$LINE" >> "$TMP_SIDEBAR"
+    ;;
+    *)
+    if [ "$WRITE" = "true" ]; then
+      echo "$LINE" >> "$TMP_SIDEBAR"
+    fi
+    ;;
+    esac
+  done < "$OWN_DIR/docs/_Sidebar.md"
+  mv "$TMP_SIDEBAR" "$OWN_DIR/docs/_Sidebar.md"
+}
+
+parse_roles_toc(){
+  ROLES=$(find "$OWN_DIR/$1" -mindepth 2 -maxdepth 2 -name "README.md" | sort)
+  for ROLE in $ROLES; do
+    WRITE="true"
+    INDENT=$(printf %$(($2 * 2))s)
+    RELATIVE=$(realpath --relative-to="$OWN_DIR" "$(dirname "$ROLE")")
+    while read -r LINE; do
+      case $LINE in
+      "# "*)
+        if [ "$WRITE" = "true" ]; then
+          TITLE=$(echo "$LINE" | cut -c 3-)
+          echo "$INDENT"" - [$TITLE]($RELATIVE)" >> "$TMP_SIDEBAR"
+          WRITE="false"
+        fi
+      ;;
+      esac
+    done < "$ROLE"
+  parse_roles_toc "$RELATIVE" $(($2 + 1))
+  done
+}
+
+rm -rf "$OWN_DIR/docs/roles"
+ROLE_PAGES=$(find "$OWN_DIR/roles" -name "README.md")
+for ROLE_PAGE in $ROLE_PAGES; do
+  parse_role_variables "$ROLE_PAGE"
+done
+for ROLE_PAGE in $ROLE_PAGES; do
+  cp_role_page "$ROLE_PAGE"
+done
+generate_roles_toc
+
+
+cp_single_page install
+cp_single_page contribute
+cp_single_page scripts

From a8aace549cb237dd0c324f0525edb164619fbafe Mon Sep 17 00:00:00 2001
From: Greg Harvey <greg.harvey@gmail.com>
Date: Wed, 8 Jan 2025 13:36:01 +0100
Subject: [PATCH 5/5] Making devel PR for docs and better error handling.

---
 .github/workflows/ce-deploy-publish-docs.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ce-deploy-publish-docs.yml b/.github/workflows/ce-deploy-publish-docs.yml
index 063ef344..29161a56 100644
--- a/.github/workflows/ce-deploy-publish-docs.yml
+++ b/.github/workflows/ce-deploy-publish-docs.yml
@@ -51,7 +51,9 @@ jobs:
 
       # Create docs pull request
       - name: Create a documentation pull request
-        run: gh pr create --base ${{ github.event.pull_request.base.ref }} --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update" --body "**Automated pull request** created by GitHub Actions because of a documentation update."
+        run: |
+          gh pr create --base ${{ github.event.pull_request.base.ref }} --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update - ${{ github.event.pull_request.base.ref }}" --body "**Automated pull request** created by GitHub Actions because of a documentation update." || echo "No commits between ${{ github.event.pull_request.base.ref }} and docs-${{ github.event.pull_request.base.ref }} - no PR created!"
+          gh pr create --base devel --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update - devel" --body "**Automated pull request** created by GitHub Actions because of a documentation update." || echo "No commits between devel and docs-${{ github.event.pull_request.base.ref }} - no PR created!"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}