Generate PHP API documentation automatically

.github/workflows/docs.yml

@@ -4,7 +4,17 @@ name: Generate and Deploy Documentation
 on:
   push:
     branches:
-      - main  # Or the branch you use for documentation
+      - main
+  pull_request:
+    paths:
+      - "src/**"
+      - "docs/**"
+      - "README.md"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: write
 
 jobs:
   build-docs:
@@ -13,23 +23,46 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      # Set up Python environment
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
           python-version: 3.11
 
-      # Install dependencies
-      - name: Install dependencies
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          coverage: none
+
+      - name: Install MkDocs dependencies
         run: |
           pip install mkdocs==1.5.3 mkdocs-material pymdown-extensions mkdocs-minify-plugin
 
-      # Build the MkDocs site
+      - name: Download phpDocumentor
+        run: |
+          curl -fsSL \
+            -o /tmp/phpDocumentor.phar \
+            https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.10.0/phpDocumentor.phar
+          echo "fe1e7c23ba3329aa6f19ac3c807446159a431a195ec5d9163b0c281a15105207  /tmp/phpDocumentor.phar" \
+            | sha256sum --check --strict
+
       - name: Build MkDocs site
         run: mkdocs build
 
-      # Deploy to GitHub Pages
+      - name: Build generated PHP API documentation
+        run: |
+          php /tmp/phpDocumentor.phar \
+            -d src \
+            -t site/api-docs \
+            --title "ELP Parser API"
+
+      - name: Verify generated documentation
+        run: |
+          test -f site/index.html
+          test -f site/api-docs/index.html
+
       - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -32,7 +32,7 @@ Parser for eXeLearning project files with support for legacy `contentv3.xml` pro
 - Streaming extraction to avoid loading large assets into memory
 - JSON serialization
 
-For more information, visit the [documentation](https://exelearning.github.io/elp-parser/). The repository also includes an `examples/` directory with executable recipes for inspection, validation, assets, diffs, fingerprints and extraction.
+For more information, visit the [documentation](https://exelearning.github.io/elp-parser/). The published site includes both the curated API guide and a PHPDoc-generated class/reference index. The repository also includes an `examples/` directory with executable recipes for inspection, validation, assets, diffs, fingerprints and extraction.
 
 ## Requirements
 

docs/phpdoc.md

@@ -0,0 +1,9 @@
+# Generated PHP API documentation
+
+The hand-written [API reference](api.md) focuses on the stable public surface and common workflows.
+
+A complete reference generated from PHPDoc is built automatically with phpDocumentor from the current `src/` tree:
+
+[Open generated PHP API documentation](../api-docs/index.html)
+
+The documentation workflow uses a pinned phpDocumentor release and verifies its SHA-256 checksum before execution. Pull requests that change source or documentation build the site without deploying it; only pushes to `main` publish GitHub Pages.

mkdocs.yml

@@ -65,6 +65,7 @@ nav:
       - Cookbook: cookbook.md
       - Detailed JSON Schema: json-schema.md
   - API Reference: api.md
+  - Generated PHP API: phpdoc.md
 
 markdown_extensions:
   - pymdownx.highlight: