[Add] apigen helper script to run dockerized ApiGen, (#738)

[Change] Generate ApiGen to build directory and Ignore ApIGen Output,
[Change] Refactor Documentation workflow into seperate ApiGen & GitHub Pages jobs

.github/workflows/Documentation.yml

@@ -11,45 +11,54 @@ jobs:
     runs-on: ubuntu-22.04
     name: ApiGen
     steps:
-      - name: Checkout source
+      - name: Checkout Project
         uses: actions/checkout@v4
         with:
           fetch-depth: 10
-          path: source
-
-      - name: Checkout gh-pages
+
+      - name: Run ApiGen
+        run: bin/apigen
+
+      - name: Upload ApiGen output artifact
+        # Require non local GitHub Actions Runner & the projects default branch
+        if: env.ACT != 'true' && ${{ format('refs/heads/{0}', github.event.repository.default_branch) == github.ref }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: apigen
+          path: build/apigen
+
+  pages:
+    runs-on: ubuntu-22.04
+    name: GitHub Pages
+    # Require non local GitHub Actions Runner & the projects default branch
+    if: env.ACT != 'true' && ${{ format('refs/heads/{0}', github.event.repository.default_branch) == github.ref }}
+    steps:
+      - name: Checkout GitHub Pages
         uses: actions/checkout@v4
         with:
           fetch-depth: 10
           ref: gh-pages
-          path: gh-pages
-
-      - name: Validate composer.json
-        run: |
-             cd source
-             composer validate
-        
-      - name: Cache composer files
-        uses: actions/cache@v4
+
+      - name: Remove old ApiGen
+        run: rm -r api
+
+      - name: Download current ApiGen
+        uses: actions/download-artifact@v4
+        with:
+          name: apigen
+          path: api
+
+      - name: Download current README
+        uses: actions/checkout@v4
         with:
-          path: ~/.composer/cache/files
-          key: dependencies-php-${{ matrix.php }}-composer-${{ hashFiles('source/composer.json') }}
-
-      - name: Install dependencies using composer
-        run: |
-             cd source
-             composer install --prefer-dist --no-interaction ${{ matrix.composer-extra }}
-       
-      - name: Clean old ApiGen
-        run: |
-             rm -rf gh-pages/api
-             mkdir -p gh-pages/api
-          
-      - name: ApiGen
-        run: docker run --rm --interactive --user $(id -u):$(id -g) --volume "$PWD:$PWD" --workdir "$PWD/source" apigen/apigen:edge src --output ../gh-pages/api
-
-      - name: Commit & Push updated file
-        if: ${{ always() }} && env.ACT != 'true'
+          sparse-checkout: |
+            README.md
+          sparse-checkout-cone-mode: false
+
+      - name: Update GitHub Pages index from README
+        run: mv README.md index.md
+
+      - name: Commit & Push GitHub Pages
         uses: EndBug/add-and-commit@v9
         with:
           default_author: github_actor

.gitignore

@@ -14,6 +14,9 @@ vendor
 composer.lock
 composer.phar
 
+# ApiGen
+build/apigen
+
 # PHPUnit
 phpunit.xml
 .phpunit.result.cache

bin/apigen

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+###################################################################
+# This executable helper does act as a wrapper for the dockerized #
+# ApiGen tool. This allows to conveniently run ApiGen while not   #
+# relying on the CI.                                              #
+###################################################################
+
+# Set the directory to the project root directory
+PROJECT_DIR="$(dirname "$(realpath $0)")/.."
+
+# Define the internal working directory
+INTERNAL_DIR="/GameQ"
+
+# Ensure the ApiGen directory does exit
+mkdir -p $PROJECT_DIR/build/apigen
+
+# Start building the Docker run command
+CMD=( docker run )
+
+# Run Docker container as the current user / group to prevent permission issues
+CMD+=( --user $(id -u):$(id -g) )
+
+# Mount the project directory into the Docker Container
+CMD+=( --volume "$PROJECT_DIR":"$INTERNAL_DIR" )
+
+# Change Docker containers working directory
+CMD+=( --workdir $INTERNAL_DIR )
+
+# Define Docker image to be used for ApiGen
+CMD+=( apigen/apigen:edge )
+
+# Configure ApiGen working directory
+CMD+=( src )
+
+# Configure the ApiGen output directory
+CMD+=( --output build/apigen )
+
+# Concatenate and run the command
+"${CMD[@]}"