From 9b6ecf2dfd5a26017ac80f2447d6470fcd613600 Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:00:40 +0100
Subject: [PATCH 1/4] Generate PHP API documentation with phpDocumentor

---
 .github/workflows/docs.yml | 45 +++++++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 1042ce3..d0e10bc 100644
--- a/.github/workflows/docs.yml
+++ b/.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 }}

From ca593b1b7497e846e282a674eea89ea7eea74620 Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:00:42 +0100
Subject: [PATCH 2/4] Document generated PHP API reference

---
 docs/phpdoc.md | 9 +++++++++
 1 file changed, 9 insertions(+)
 create mode 100644 docs/phpdoc.md

diff --git a/docs/phpdoc.md b/docs/phpdoc.md
new file mode 100644
index 0000000..eeaa29d
--- /dev/null
+++ b/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.

From 032635fe79f5af4b958a7ba10be05ba073e2a8a8 Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:00:45 +0100
Subject: [PATCH 3/4] Link generated PHP API documentation

---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index e47014d..e908822 100644
--- a/mkdocs.yml
+++ b/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:

From 424538369116524516e6a0106d2f787530c5127c Mon Sep 17 00:00:00 2001
From: Ernesto Serrano <info@ernesto.es>
Date: Sat, 19 Sep 2026 22:00:47 +0100
Subject: [PATCH 4/4] Link generated API documentation from README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 020efec..43aa0d5 100644
--- a/README.md
+++ b/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