Move SDK docs generation to post-merge workflow (#1513)

.github/workflows/run-static.yml

@@ -42,8 +42,6 @@ jobs:
           python-version: "3.12"
       - name: Install dependencies
         run: uv sync --dev
-      - name: Install just
-        uses: extractions/setup-just@v3
       - name: Check lockfile is up to date
         run: |
           if ! uv lock --check; then
@@ -56,33 +54,3 @@ jobs:
         uses: pre-commit/action@v3.0.1
         env:
           SKIP: no-commit-to-branch
-      - name: Check SDK documentation is up to date
-        run: |
-          # Save original docs.json for comparison
-          cp docs/docs.json docs/docs.json.orig
-
-          # Generate documentation
-          just api-ref-all > /dev/null 2>&1
-
-          # Check if python-sdk files changed
-          if ! git diff --quiet docs/python-sdk/; then
-            echo "❌ SDK documentation is out of date!"
-            echo "Files that were updated:"
-            git diff --name-only docs/python-sdk/
-            echo ""
-            echo "Run `just api-ref-all` to regenerate the SDK docs, then commit the changes. Note: you may need to install `just` (https://github.com/casey/just)"
-            exit 1
-          fi
-
-          # Check if docs.json content changed (ignoring formatting)
-          if ! jq --sort-keys . docs/docs.json.orig | diff -q - <(jq --sort-keys . docs/docs.json) > /dev/null 2>&1; then
-            echo "❌ docs.json content has changed!"
-            echo ""
-            echo "Run `just api-ref-all` to regenerate the SDK docs, then commit the changes. Note: you may need to install `just` (https://github.com/casey/just)"
-            exit 1
-          fi
-
-          # Restore original docs.json to avoid false positives
-          mv docs/docs.json.orig docs/docs.json
-
-          echo "✅ SDK documentation is up to date"

.github/workflows/update-sdk-docs.yml

@@ -0,0 +1,81 @@
+name: Update SDK Documentation
+
+# This workflow runs on merges to main to automatically update SDK docs
+# without blocking PRs. SDK doc generation can fail if another PR merges
+# first, so handling it post-merge prevents annoying CI failures for contributors.
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-sdk-docs:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Generate SDK documentation
+        run: |
+          echo "🔄 Generating SDK documentation..."
+          just api-ref-all
+
+      - name: Check for changes
+        id: check_changes
+        run: |
+          if git diff --quiet docs/python-sdk/ docs/docs.json; then
+            echo "No changes detected in SDK documentation"
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "Changes detected in SDK documentation"
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and push changes
+        if: steps.check_changes.outputs.has_changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add docs/python-sdk/ docs/docs.json
+          git commit -m "chore: Update SDK documentation
+
+          🤖 Generated with [Claude Code](https://claude.ai/code)
+
+          Co-Authored-By: Claude <noreply@anthropic.com>"
+          git push
+
+      - name: Summary
+        run: |
+          if [ "${{ steps.check_changes.outputs.has_changes }}" == "true" ]; then
+            echo "✅ SDK documentation updated and committed"
+          else
+            echo "✅ SDK documentation is already up to date"
+          fi