docs/.github/workflows/update-api-docs.yml at astro · codellm-devkit/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: Update Python API reference

# Regenerates src/content/docs/reference/python-api/*.md from a python-sdk release
# and opens a PR when anything changed. This keeps the *source-controlled* API
# reference matched to the SDK; the deploy workflow regenerates the same docs
# ephemerally for the published build, but never commits them back.
#
# Trigger: a python-sdk *release* only. python-sdk's release workflow
# (.github/workflows/release.yml) sends a repository_dispatch after it publishes,
# carrying the released tag in client_payload.ref:
#
#   - name: Trigger docs API-reference update
#     uses: peter-evans/repository-dispatch@v3
#     with:
#       token: ${{ secrets.DOCS_DISPATCH_TOKEN }}   # PAT/fine-grained token with
#                                                    # contents:write on codellm-devkit/docs
#       repository: codellm-devkit/docs
#       event-type: sdk-release
#       client-payload: '{"ref": "${{ github.ref_name }}"}'

on:
  repository_dispatch:
    types: [sdk-release]

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: update-api-docs
  cancel-in-progress: true

jobs:
  regenerate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout docs
        uses: actions/checkout@v4
        with:
          ref: astro

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Clone python-sdk at the released tag
        id: sdk
        run: |
          set -euo pipefail
          git clone https://github.com/codellm-devkit/python-sdk.git ../python-sdk
          cd ../python-sdk
          # The release workflow sends the released tag in client_payload.ref.
          # Fall back to the latest release tag if a dispatch ever arrives without one.
          REF="${{ github.event.client_payload.ref }}"
          if [ -z "${REF}" ]; then
            REF=$(git tag --sort=-v:refname | head -n1)
          fi
          echo "Generating API reference from python-sdk release: ${REF}"
          git checkout "${REF}"
          SDK_VERSION=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
          echo "ref=${REF}" >> "$GITHUB_OUTPUT"
          echo "version=${SDK_VERSION}" >> "$GITHUB_OUTPUT"

      - name: Install the SDK and the generator deps
        run: |
          set -euo pipefail
          python -m pip install --upgrade pip
          # Installing cldk pulls in the codeanalyzer-* backends whose models the
          # schema pages re-export (needed for griffe alias resolution).
          pip install -e ../python-sdk
          pip install -r scripts/requirements.txt

      - name: Regenerate API reference markdown
        run: python scripts/gen_api_docs.py

      - name: Open a PR if the reference changed
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          base: astro
          branch: auto/api-docs
          add-paths: src/content/docs/reference/python-api/**
          commit-message: "docs(api): sync Python API reference to python-sdk ${{ steps.sdk.outputs.version }}"
          title: "docs(api): sync Python API reference to python-sdk ${{ steps.sdk.outputs.version }}"
          body: |
            Automated regeneration of the Python API reference from the
            [`python-sdk`](https://github.com/codellm-devkit/python-sdk) release
            `${{ steps.sdk.outputs.ref }}` (version `${{ steps.sdk.outputs.version }}`).

            Generated by `scripts/gen_api_docs.py` (griffe). Authored intros above the
            `CLDK:API:START` markers are preserved; only the generated symbol
            reference changed. Review the diff and merge to ship.
          labels: documentation, automated
          delete-branch: true