fix: switch broken apigen workflow to phpDocumentor

The varunsridharan/action-apigen action pulled in apigen 4.1.2, whose
transitive dependency herrera-io/json points at a GitHub source repo
that no longer exists, breaking installs. Replace with phpDocumentor
via phpdocumentor/shim (no PHP version constraints), expose a
"composer docs" script for local previews, and rewrite the workflow
to build and publish to gh-pages on successful test runs.

Author: splitbrain

.github/workflows/apigen.yml

@@ -10,11 +10,28 @@ on:
 jobs:
   Document_Generator:
     runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
-      - uses: actions/checkout@v2
-      - name: 📝 ApiGen PHP Document Generator
-        uses: varunsridharan/action-apigen@2.1
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress
+
+      - name: Generate API docs
+        run: composer docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          cached_apigen: 'no'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          commit_message: 'Docs updated by GitHub Actions'

.gitignore

@@ -5,4 +5,5 @@ vendor/
 composer.lock
 apigen.phar
 docs/
+.phpdoc/
 .phpunit.result.cache

apigen.neon

@@ -24,11 +24,20 @@
     "psr/log": "Allows you to make the CLI available as PSR-3 logger"
   },
   "require-dev": {
-    "phpunit/phpunit": "^8"
+    "phpunit/phpunit": "^8",
+    "phpdocumentor/shim": "^3"
   },
   "autoload": {
     "psr-4": {
       "splitbrain\\phpcli\\": "src"
     }
+  },
+  "scripts": {
+    "docs": "phpdoc -d src -t docs --no-interaction"
+  },
+  "config": {
+    "allow-plugins": {
+      "phpdocumentor/shim": true
+    }
   }
 }