ci: add SDK API reference sync workflows for TypeScript and Python

.github/workflows/sync-python-sdk-docs.yaml

@@ -0,0 +1,144 @@
+name: Sync Python SDK API Reference
+
+on:
+  schedule:
+    - cron: "0 16 * * 4" # Runs every Thursday at 4 PM UTC (1h after REST API sync)
+  workflow_dispatch:
+    inputs:
+      docs_version:
+        description: "Docs version to update (e.g. '8.8'). Leave empty for next (docs/)."
+        required: false
+        default: ""
+      sdk_ref:
+        description: "Git ref of the Python SDK repo. Ignored when docs_version is set (uses stable/<version>)."
+        required: false
+        default: "main"
+      dry_run:
+        description: "Dry run — generate docs but skip PR creation"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  sync-python-sdk-docs:
+    runs-on: ubuntu-latest
+    env:
+      DOCS_VERSION: ${{ github.event.inputs.docs_version || '' }}
+    steps:
+      - name: Resolve refs and paths
+        id: resolve
+        run: |
+          VERSION="${{ github.event.inputs.docs_version }}"
+          if [ -n "$VERSION" ]; then
+            echo "sdk_ref=stable/${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "docs_root=versioned_docs/version-${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "pr_branch=update-python-sdk-docs/${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "version_label=${VERSION}" >> "$GITHUB_OUTPUT"
+          else
+            echo "sdk_ref=${{ github.event.inputs.sdk_ref || 'main' }}" >> "$GITHUB_OUTPUT"
+            echo "docs_root=docs" >> "$GITHUB_OUTPUT"
+            echo "pr_branch=update-python-sdk-docs" >> "$GITHUB_OUTPUT"
+            echo "version_label=next" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout camunda-docs
+        uses: actions/checkout@v4
+        with:
+          repository: camunda/camunda-docs
+          path: docs
+
+      - name: Checkout Python SDK
+        uses: actions/checkout@v4
+        with:
+          repository: camunda/orchestration-cluster-api-python
+          ref: ${{ steps.resolve.outputs.sdk_ref }}
+          path: python-sdk
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Generate Python SDK (required for docs)
+        working-directory: python-sdk
+        run: |
+          uv sync
+          make generate-local
+
+      - name: Build markdown docs
+        working-directory: python-sdk
+        run: make docs-md
+
+      - name: Copy docs into camunda-docs
+        run: |
+          DOCS_ROOT="docs/${{ steps.resolve.outputs.docs_root }}"
+          TARGET="$DOCS_ROOT/apis-tools/python-sdk"
+
+          # Clean previous generated docs
+          rm -rf "$TARGET"
+          rm -f "$DOCS_ROOT/apis-tools/python-sdk.md"
+          mkdir -p "$TARGET"
+
+          # Copy landing page (sibling of the directory, avoids duplicate sidebar entry)
+          cp python-sdk/public/markdown/python-sdk.md "$DOCS_ROOT/apis-tools/python-sdk.md"
+
+          # Copy section pages + api-reference
+          cp -R python-sdk/public/markdown/python-sdk/* "$TARGET/"
+
+          SECTION_COUNT=$(find "$TARGET" -maxdepth 1 -name '*.md' | wc -l | tr -d ' ')
+          API_COUNT=$(find "$TARGET/api-reference" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
+          echo "Copied landing page + ${SECTION_COUNT} section pages + ${API_COUNT} API reference files → ${{ steps.resolve.outputs.docs_root }}"
+
+      - name: Check for changes
+        id: check_changes
+        working-directory: docs
+        run: |
+          if git diff-index --quiet HEAD; then
+            echo "No changes to commit."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Changes detected."
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate token
+        if: steps.check_changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'
+        id: generate_token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.GH_APP_API_SYNC_ID }}
+          private-key: ${{ secrets.GH_APP_API_SYNC_KEY }}
+
+      - name: Create Pull Request
+        if: steps.check_changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: "${{ steps.generate_token.outputs.token }}"
+          path: docs
+          title: "docs: update Python SDK API reference (${{ steps.resolve.outputs.version_label }})"
+          body: |
+            ## Description
+
+            Auto-generated PR from the [sync Python SDK docs workflow](https://github.com/camunda/camunda-docs/tree/main/.github/workflows/sync-python-sdk-docs.yaml).
+
+            Updates the Python SDK API reference documentation from [`orchestration-cluster-api-python@${{ steps.resolve.outputs.sdk_ref }}`](https://github.com/camunda/orchestration-cluster-api-python/tree/${{ steps.resolve.outputs.sdk_ref }}).
+
+            **Target:** `${{ steps.resolve.outputs.docs_root }}/apis-tools/python-sdk/`
+
+            ## When should this change go live?
+
+            - There is **no urgency** with this change and can be released at any time.
+
+            ## PR Checklist
+
+            - My changes are in `/${{ steps.resolve.outputs.docs_root }}`.
+          commit-message: "docs: update Python SDK API reference (${{ steps.resolve.outputs.version_label }})"
+          branch: ${{ steps.resolve.outputs.pr_branch }}
+          delete-branch: true
+          base: main
+          labels: deploy

.github/workflows/sync-ts-sdk-docs.yaml

@@ -0,0 +1,130 @@
+name: Sync TypeScript SDK API Reference
+
+on:
+  schedule:
+    - cron: "0 16 * * 4" # Runs every Thursday at 4 PM UTC (1h after REST API sync)
+  workflow_dispatch:
+    inputs:
+      docs_version:
+        description: "Docs version to update (e.g. '8.8'). Leave empty for next (docs/)."
+        required: false
+        default: ""
+      sdk_ref:
+        description: "Git ref of the JS SDK repo. Ignored when docs_version is set (uses stable/<version>)."
+        required: false
+        default: "main"
+      dry_run:
+        description: "Dry run — generate docs but skip PR creation"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  sync-ts-sdk-docs:
+    runs-on: ubuntu-latest
+    env:
+      DOCS_VERSION: ${{ github.event.inputs.docs_version || '' }}
+    steps:
+      - name: Resolve refs and paths
+        id: resolve
+        run: |
+          VERSION="${{ github.event.inputs.docs_version }}"
+          if [ -n "$VERSION" ]; then
+            echo "sdk_ref=stable/${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "docs_root=versioned_docs/version-${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "pr_branch=update-ts-sdk-docs/${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "version_label=${VERSION}" >> "$GITHUB_OUTPUT"
+          else
+            echo "sdk_ref=${{ github.event.inputs.sdk_ref || 'main' }}" >> "$GITHUB_OUTPUT"
+            echo "docs_root=docs" >> "$GITHUB_OUTPUT"
+            echo "pr_branch=update-ts-sdk-docs" >> "$GITHUB_OUTPUT"
+            echo "version_label=next" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout camunda-docs
+        uses: actions/checkout@v4
+        with:
+          repository: camunda/camunda-docs
+          path: docs
+
+      - name: Checkout TypeScript SDK
+        uses: actions/checkout@v4
+        with:
+          repository: camunda/orchestration-cluster-api-js
+          ref: ${{ steps.resolve.outputs.sdk_ref }}
+          path: ts-sdk
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        working-directory: ts-sdk
+        run: npm ci
+
+      - name: Build markdown docs
+        working-directory: ts-sdk
+        run: npm run docs:md
+
+      - name: Copy docs into camunda-docs
+        run: |
+          TARGET="docs/${{ steps.resolve.outputs.docs_root }}/apis-tools/typescript/api-reference"
+
+          # Clean previous generated docs (preserve manually-maintained files)
+          rm -rf "$TARGET"
+          mkdir -p "$TARGET"
+
+          # Copy the full docs-md tree
+          cp -R ts-sdk/docs-md/* "$TARGET/"
+
+          echo "Copied $(find "$TARGET" -name '*.md' | wc -l) markdown files → ${{ steps.resolve.outputs.docs_root }}"
+
+      - name: Check for changes
+        id: check_changes
+        working-directory: docs
+        run: |
+          if git diff-index --quiet HEAD; then
+            echo "No changes to commit."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Changes detected."
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate token
+        if: steps.check_changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'
+        id: generate_token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.GH_APP_API_SYNC_ID }}
+          private-key: ${{ secrets.GH_APP_API_SYNC_KEY }}
+
+      - name: Create Pull Request
+        if: steps.check_changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: "${{ steps.generate_token.outputs.token }}"
+          path: docs
+          title: "docs: update TypeScript SDK API reference (${{ steps.resolve.outputs.version_label }})"
+          body: |
+            ## Description
+
+            Auto-generated PR from the [sync TypeScript SDK docs workflow](https://github.com/camunda/camunda-docs/tree/main/.github/workflows/sync-ts-sdk-docs.yaml).
+
+            Updates the TypeScript SDK API reference documentation from [`orchestration-cluster-api-js@${{ steps.resolve.outputs.sdk_ref }}`](https://github.com/camunda/orchestration-cluster-api-js/tree/${{ steps.resolve.outputs.sdk_ref }}).
+
+            **Target:** `${{ steps.resolve.outputs.docs_root }}/apis-tools/typescript/api-reference/`
+
+            ## When should this change go live?
+
+            - There is **no urgency** with this change and can be released at any time.
+
+            ## PR Checklist
+
+            - My changes are in `/${{ steps.resolve.outputs.docs_root }}`.
+          commit-message: "docs: update TypeScript SDK API reference (${{ steps.resolve.outputs.version_label }})"
+          branch: ${{ steps.resolve.outputs.pr_branch }}
+          delete-branch: true
+          base: main
+          labels: deploy

.gitignore

@@ -25,3 +25,4 @@ node_modules
 /test-results/
 /playwright-report/
 /playwright/.cache/
+/python-sdk

.vale.ini

@@ -2,3 +2,22 @@ StylesPath = "styles/camunda"
 
 [{docs,versioned_docs}/**/*.{md,mdx}]
 BasedOnStyles = all
+
+# Generated SDK API reference — language/terminology rules are relaxed
+# because the content originates from upstream OpenAPI specifications
+# and SDK-generated code that we do not control.
+# Link rules remain active so broken or non-relative URLs are caught.
+[{docs,versioned_docs}/**/apis-tools/typescript/api-reference/**/*.md]
+all.americanBritish = NO
+all.inclusiveLanguage = NO
+all.glossary = NO
+
+[{docs,versioned_docs}/**/apis-tools/python-sdk/**/*.md]
+all.americanBritish = NO
+all.inclusiveLanguage = NO
+all.glossary = NO
+
+[{docs,versioned_docs}/**/apis-tools/csharp-sdk/**/*.md]
+all.americanBritish = NO
+all.inclusiveLanguage = NO
+all.glossary = NO