feat: github action

Author: davidturnbull

.github/workflows/generate-docs.yml

@@ -0,0 +1,49 @@
+name: Generate Markdown Docs
+
+on:
+  push:
+    branches:
+      - '*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  generate:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.1'
+          extensions: mbstring, intl
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Generate Markdown documentation
+        run: vendor/bin/phpdoc --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"
+
+      - name: Commit and push updates
+        run: |
+          STATUS=$(git status --short docs)
+          if [ -z "$STATUS" ]; then
+            echo "Documentation already up to date"
+            exit 0
+          fi
+
+          echo "Docs updated, committing changes"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs
+          git commit -m "docs: update markdown API reference [skip ci]"
+          git push

.gitignore

@@ -3,3 +3,4 @@
 .env
 /demo/vendor/
 /demo/composer.lock
+.phpdoc/cache

composer.json

@@ -12,10 +12,12 @@
     "require": {
         "php": "^8.1",
         "guzzlehttp/guzzle": "^7.0",
-        "respect/validation": "^2.0"
+        "respect/validation": "^2.0",
+        "phpdocumentor/shim": "^3.8"
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.0"
+        "phpunit/phpunit": "^9.0",
+        "saggre/phpdocumentor-markdown": "^1.0"
     },
     "autoload": {
         "psr-4": {
@@ -26,5 +28,10 @@
         "psr-4": {
             "LingoDotDev\\Sdk\\Tests\\": "tests/"
         }
+    },
+    "config": {
+        "allow-plugins": {
+            "phpdocumentor/shim": true
+        }
     }
 }

src/LingoDotDevEngine.php

@@ -97,7 +97,7 @@ public function __construct(array $config = [])
      *
      * @param array<string, mixed>         $payload          Content to translate, structured as key-value pairs
      * @param array<string, mixed>         $params           Translation configuration options
-     * @param callable(int, mixed, mixed): void|null $progressCallback Callback invoked with completion percentage (0-100), current chunk, and processed chunk
+     * @param null|callable(int, mixed, mixed): void $progressCallback Callback invoked with completion percentage (0-100), current chunk, and processed chunk
      *
      * @return array<string, mixed> Translated content maintaining original structure
      *
@@ -300,7 +300,7 @@ private function _createId(): string
      *                                                - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
      *                                                - 'fast' (bool): Trade translation quality for speed
      *                                                - 'reference' (array): Context or glossary terms to guide translation
-     * @param callable(int, mixed, mixed): void|null $progressCallback Invoked per batch with (percentage complete, current batch, translated batch)
+     * @param null|callable(int, mixed, mixed): void $progressCallback Invoked per batch with (percentage complete, current batch, translated batch)
      *
      * @return array<string, mixed> Translated data preserving original structure and non-text values
      *
@@ -329,7 +329,7 @@ public function localizeObject(array $obj, array $params, ?callable $progressCal
      *                                                          - 'sourceLocale' (string|null): Language code of original text, null for auto-detection
      *                                                          - 'fast' (bool): Prioritize speed over translation quality
      *                                                          - 'reference' (array): Context, terminology, or style guidelines for translation
-     * @param callable(int): void|null $progressCallback Called with completion percentage (0-100) during processing
+     * @param null|callable(int): void $progressCallback Called with completion percentage (0-100) during processing
      *
      * @return string Translated text, or empty string if translation unavailable
      *
@@ -398,7 +398,7 @@ public function batchLocalizeText(string $text, array $params): array
      *                                                                          - 'sourceLocale' (string|null): Language of original messages, null for auto-detection
      *                                                                          - 'fast' (bool): Optimize for speed over translation quality
      *                                                                          - 'reference' (array): Conversation context or domain-specific terminology
-     * @param callable(int): void|null                       $progressCallback Called with completion percentage (0-100) during processing
+     * @param null|callable(int): void                       $progressCallback Called with completion percentage (0-100) during processing
      *
      * @return array<int, array{name: string, text: string}> Translated messages keeping original speaker names unchanged
      *