Flatten API reference into single file using pydoc-markdown #2
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
