docs: revise docs for PHP SDK

.github/workflows/generate-docs.yml

@@ -0,0 +1,55 @@
+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" \
+            --title="PHP SDK for Lingo.dev" \
+            --visibility=public
+
+      - 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
+        }
     }
 }

docs/Home.md

@@ -0,0 +1,15 @@
+
+This is an automatically generated documentation for **PHP SDK for Lingo.dev**.
+
+## Namespaces
+
+### \LingoDotDev\Sdk
+
+#### Classes
+
+| Class                                                                          | Description                                                               |
+|--------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| [`BatchTranslationOptions`](./classes/LingoDotDev/Sdk/BatchTranslationOptions) | Options for batch text translation to multiple languages.                 |
+| [`EngineConfig`](./classes/LingoDotDev/Sdk/EngineConfig)                       | Configuration for LingoDotDevEngine initialization.                       |
+| [`LingoDotDevEngine`](./classes/LingoDotDev/Sdk/LingoDotDevEngine)             | LingoDotDevEngine wraps the Lingo.dev localization API for PHP consumers. |
+| [`TranslationOptions`](./classes/LingoDotDev/Sdk/TranslationOptions)           | Options for text and object translation.                                  |

docs/classes/LingoDotDev/Sdk/BatchTranslationOptions.md

@@ -0,0 +1,106 @@
+
+Options for batch text translation to multiple languages.
+
+***
+
+* Full name: `\LingoDotDev\Sdk\BatchTranslationOptions`
+
+**See Also:**
+
+* https://lingo.dev
+
+## Properties
+
+### sourceLocale
+
+Source language code (e.g., 'en')
+Required field.
+
+```php
+public string $sourceLocale
+```
+
+***
+
+### targetLocales
+
+Array of target language codes (e.g., ['es', 'fr', 'de'])
+Required field.
+
+```php
+public string[] $targetLocales
+```
+
+***
+
+### fast
+
+Enable fast mode - trades translation quality for speed
+Default: false (quality mode)
+
+```php
+public bool $fast
+```
+
+***
+
+## Methods
+
+### create
+
+Create a fluent builder for batch translation options.
+
+```php
+public static create(string $sourceLocale): self
+```
+
+* This method is **static**.
+**Parameters:**
+
+| Parameter       | Type       | Description          |
+|-----------------|------------|----------------------|
+| `$sourceLocale` | **string** | Source language code |
+
+***
+
+### to
+
+Set target locales.
+
+```php
+public to(string[] $locales): self
+```
+
+**Parameters:**
+
+| Parameter  | Type         | Description           |
+|------------|--------------|-----------------------|
+| `$locales` | **string[]** | Target language codes |
+
+***
+
+### addTarget
+
+Add a single target locale.
+
+```php
+public addTarget(string $locale): self
+```
+
+**Parameters:**
+
+| Parameter | Type       | Description          |
+|-----------|------------|----------------------|
+| `$locale` | **string** | Target language code |
+
+***
+
+### withFastMode
+
+Enable fast translation mode.
+
+```php
+public withFastMode(): self
+```
+
+***

docs/classes/LingoDotDev/Sdk/EngineConfig.md

@@ -0,0 +1,119 @@
+
+Configuration for LingoDotDevEngine initialization.
+
+***
+
+* Full name: `\LingoDotDev\Sdk\EngineConfig`
+
+**See Also:**
+
+* https://lingo.dev
+
+## Properties
+
+### apiKey
+
+Your Lingo.dev API token
+
+```php
+public string $apiKey
+```
+
+***
+
+### apiUrl
+
+API base URL (default: https://engine.lingo.dev)
+
+```php
+public string $apiUrl
+```
+
+***
+
+### batchSize
+
+Maximum records per request (1-250, default: 25)
+
+```php
+public int $batchSize
+```
+
+***
+
+### idealBatchItemSize
+
+Maximum words per request (1-2500, default: 250)
+
+```php
+public int $idealBatchItemSize
+```
+
+***
+
+## Methods
+
+### create
+
+Create configuration with API key.
+
+```php
+public static create(string $apiKey): self
+```
+
+* This method is **static**.
+**Parameters:**
+
+| Parameter | Type       | Description              |
+|-----------|------------|--------------------------|
+| `$apiKey` | **string** | Your Lingo.dev API token |
+
+***
+
+### withApiUrl
+
+Set custom API URL.
+
+```php
+public withApiUrl(string $url): self
+```
+
+**Parameters:**
+
+| Parameter | Type       | Description      |
+|-----------|------------|------------------|
+| `$url`    | **string** | API endpoint URL |
+
+***
+
+### withBatchSize
+
+Set batch size limit.
+
+```php
+public withBatchSize(int $size): self
+```
+
+**Parameters:**
+
+| Parameter | Type    | Description                 |
+|-----------|---------|-----------------------------|
+| `$size`   | **int** | Records per request (1-250) |
+
+***
+
+### withIdealBatchItemSize
+
+Set ideal batch item size.
+
+```php
+public withIdealBatchItemSize(int $size): self
+```
+
+**Parameters:**
+
+| Parameter | Type    | Description                    |
+|-----------|---------|--------------------------------|
+| `$size`   | **int** | Max words per request (1-2500) |
+
+***