ci: restore sync-docs-code-blocks workflow from main and extend to generate API docs\n\n- Restores deleted .github/workflows/sync-docs-code-blocks.yml\n- Adds API docs generation step to run alongside code block sync\n- Uses PR-based update flow on schedule via peter-evans/create-pull-request\n\nCo-authored-by: openhands <[email protected]>

Author: enyst

.github/workflows/sync-docs-code-blocks.yml

@@ -0,0 +1,97 @@
+name: Sync Documentation Code Blocks
+
+on:
+  schedule:
+    # Run daily at 2 AM UTC to catch any changes
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+    inputs:
+      agent_sdk_ref:
+        description: 'Agent SDK branch/tag/commit to sync from'
+        required: false
+        default: 'main'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync-code-blocks:
+    runs-on: ubuntu-latest
+    if: github.actor != 'github-actions[bot]'
+    steps:
+      - name: Checkout docs repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Checkout agent-sdk
+        uses: actions/checkout@v4
+        with:
+          repository: OpenHands/software-agent-sdk
+          path: agent-sdk
+          ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies for API docs
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx-markdown-builder myst-parser
+
+      - name: Sync code blocks
+        env:
+          AGENT_SDK_PATH: ${{ github.workspace }}/agent-sdk
+        shell: bash
+        run: |
+          set -euo pipefail
+          python .github/scripts/sync_code_blocks.py
+
+      - name: Generate API documentation
+        shell: bash
+        run: |
+          set -euo pipefail
+          python scripts/generate-api-docs.py
+
+      - name: Check for changes
+        id: detect_changes
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ -n "$(git status --porcelain)" ]]; then
+            echo "changes=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changes=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create Pull Request
+        if: steps.detect_changes.outputs.changes == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: |
+            docs: sync code blocks and generate API reference
+
+            Synced from agent-sdk ref: ${{ github.event.inputs.agent_sdk_ref || 'main' }}
+          branch: sync-docs-and-api
+          branch-suffix: timestamp
+          delete-branch: true
+          title: "docs: sync code blocks and generate API reference"
+          body: |
+            ## Summary of changes
+
+            This PR automatically syncs code blocks in documentation with their corresponding source files from the agent-sdk repository, and generates API reference documentation.
+
+            **Agent SDK Reference**: `${{ github.event.inputs.agent_sdk_ref || 'main' }}`
+
+            ### Changes Made
+            - Updated code blocks in MDX files to match the current state of example files in agent-sdk
+            - Generated API reference markdown files
+            - This is an automated sync performed by the `sync-docs-code-blocks` workflow
+
+            ### Checklist
+            - [x] I have read and reviewed the documentation changes to the best of my ability.
+            - [x] If the change is significant, I have run the documentation site locally and confirmed it renders as expected.