docs/.github/workflows/sync-docs-code-blocks.yml at main · OpenHands/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
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

concurrency:
  group: sync-docs-code-blocks
  cancel-in-progress: true

jobs:
  sync-code-blocks:
    runs-on: ubuntu-latest
    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.12'

      - 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'
        id: cpr
        uses: peter-evans/create-pull-request@v7
        with:
          # Use github.token to create PR as github-actions[bot]
          token: ${{ github.token }}
          branch-token: ${{ github.token }}
          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.

      # Auto-approve using ALLHANDS_BOT_TOKEN (all-hands-bot). PR is created by
      # github-actions[bot], so a different identity (all-hands-bot) can approve it.
      - name: Auto-approve PR
        if: steps.cpr.outputs.pull-request-url && secrets.ALLHANDS_BOT_TOKEN != ''
        env:
          GH_TOKEN: ${{ secrets.ALLHANDS_BOT_TOKEN }}
        run: |
          gh pr review "${{ steps.cpr.outputs.pull-request-url }}" \
            --approve \
            --body "Auto-approving automated docs sync PR."

      - name: Enable auto-merge (squash)
        if: steps.cpr.outputs.pull-request-url && secrets.ALLHANDS_BOT_TOKEN != ''
        env:
          GH_TOKEN: ${{ secrets.ALLHANDS_BOT_TOKEN }}
        run: |
          PR_URL="${{ steps.cpr.outputs.pull-request-url }}"

          # Prefer auto-merge (merges when required checks finish).
          # If auto-merge isn't enabled for the repo, fall back to attempting an immediate merge.
          gh pr merge "$PR_URL" --auto --delete-branch --squash \
            || gh pr merge "$PR_URL" --delete-branch --squash