docs/.github/workflows/sync-api-reference.yml at 98dfce09a0b13a3eed9ea07b9841007d17aa2136 · 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
name: Sync SDK API Reference

on:
  push:
    branches:
      - '**'      # run on every branch
  schedule:
    - cron: '0 2 * * *'   # nightly catch-up at 2 AM UTC
  workflow_dispatch:
    inputs:
      agent_sdk_ref:
        description: 'Agent SDK branch/tag/commit to generate from'
        required: false
        default: 'main'

permissions:
  contents: write

jobs:
  sync-api-docs:
    runs-on: ubuntu-latest
    # Avoid infinite loops on our own commits
    if: github.actor != 'github-actions[bot]' && github.actor != 'all-hands-bot'

    env:
      # GITHUB_TOKEN is fine.
      GH_CLONE_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # For workflow_dispatch this will be set; for push/schedule it will fall back to main.
      AGENT_SDK_REF: ${{ github.event.inputs.agent_sdk_ref || 'main' }}

    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: true

      - name: Checkout agent-sdk
        uses: actions/checkout@v4
        with:
          repository: OpenHands/software-agent-sdk
          path: agent-sdk
          ref: ${{ env.AGENT_SDK_REF }}
          fetch-depth: 0
          # If private, uncomment:
          # token: ${{ env.GH_CLONE_TOKEN }}

      - name: Configure Git
        run: |
          git config user.name "all-hands-bot"
          git config user.email "contact@all-hands.dev"

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install pydoc-markdown
        run: |
          pip install pydoc-markdown

      - name: Generate API documentation
        env:
          AGENT_SDK_PATH: ${{ github.workspace }}/agent-sdk
        run: |
          set -euo pipefail
          python .github/scripts/generate_api_docs.py

      - name: Detect changes
        id: detect_changes
        run: |
          if [[ -n "$(git status --porcelain)" ]]; then
            echo "changes=true" >> "$GITHUB_OUTPUT"
          else
            echo "changes=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Commit and push API documentation
        if: steps.detect_changes.outputs.changes == 'true'
        run: |
          set -euo pipefail
          git add sdk/api/ docs.json
          # Re-check in case only unrelated files changed
          if git diff --cached --quiet; then
            echo "No API documentation changes to commit."
            exit 0
          fi

          SHA_SHORT="$(git -C agent-sdk rev-parse --short=7 HEAD || echo manual)"
          BRANCH="${AGENT_SDK_REF:-main}"

          git commit -m "docs(api): sync API reference from agent-sdk/${BRANCH} ${SHA_SHORT}

Automated sync of Python API reference documentation from software-agent-sdk"
          git push