Skip to content

Commit 82b7cbf

Browse files
rahlkrahlk
committed
docs(api): version-match Python API reference to python-sdk 1.2.0 + auto-update workflow
Regenerate src/content/docs/reference/python-api/ from cldk 1.2.0 (griffe): python.md picks up the full 1.2.0 Py* schema, and a new typescript.md documents TypeScriptAnalysis + the TS* schema (TSApplication, call graph, interfaces, enums, decorators). Add the TypeScript page to scripts/gen_api_docs.py PAGES with a house-style authored intro (preserved across regen by the injection markers), and wire "TypeScript analysis" into the sidebar and the reference index. Add .github/workflows/update-api-docs.yml: on a python-sdk release (repository_ dispatch), manual dispatch, or a weekly cron, it clones the SDK at the release tag, regenerates the reference with griffe, and opens a PR when the generated docs change — keeping the source-controlled API reference matched to the SDK (the deploy workflow only regenerates ephemerally for the published build). Also includes an expanded codeanalyzer-python backend reference page.
1 parent a9668ec commit 82b7cbf

7 files changed

Lines changed: 1334 additions & 5 deletions

File tree

‎.github/workflows/update-api-docs.yml‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
name: Update Python API reference
2+
3+
# Regenerates src/content/docs/reference/python-api/*.md from the python-sdk
4+
# release and opens a PR when anything changed. This keeps the *source-controlled*
5+
# API reference matched to the SDK; the deploy workflow regenerates the same docs
6+
# ephemerally for the published build, but never commits them back.
7+
#
8+
# Triggers:
9+
# - repository_dispatch (sdk-release): fired by python-sdk's release workflow.
10+
# Send the released ref in client_payload.ref, e.g. from python-sdk:
11+
# - uses: peter-evans/repository-dispatch@v3
12+
# with:
13+
# token: ${{ secrets.DOCS_DISPATCH_TOKEN }} # PAT with repo scope on the docs repo
14+
# repository: codellm-devkit/docs
15+
# event-type: sdk-release
16+
# client-payload: '{"ref": "${{ github.ref_name }}"}'
17+
# - workflow_dispatch: manual run, with an optional ref (tag/branch/sha).
18+
# - schedule: weekly safety net in case a release dispatch is ever missed.
19+
20+
on:
21+
repository_dispatch:
22+
types: [sdk-release]
23+
workflow_dispatch:
24+
inputs:
25+
ref:
26+
description: "python-sdk ref to generate from (tag/branch/sha). Defaults to the latest release tag."
27+
required: false
28+
default: ""
29+
schedule:
30+
- cron: "0 6 * * 1" # Mondays 06:00 UTC
31+
32+
permissions:
33+
contents: write
34+
pull-requests: write
35+
36+
concurrency:
37+
group: update-api-docs
38+
cancel-in-progress: true
39+
40+
jobs:
41+
regenerate:
42+
runs-on: ubuntu-latest
43+
steps:
44+
- name: Checkout docs
45+
uses: actions/checkout@v4
46+
with:
47+
ref: astro
48+
49+
- name: Set up Python
50+
uses: actions/setup-python@v5
51+
with:
52+
python-version: "3.12"
53+
54+
- name: Clone python-sdk at the target ref
55+
id: sdk
56+
run: |
57+
set -euo pipefail
58+
git clone https://github.com/codellm-devkit/python-sdk.git ../python-sdk
59+
cd ../python-sdk
60+
# Precedence: repository_dispatch payload > workflow_dispatch input > latest release tag.
61+
REF="${{ github.event.client_payload.ref || github.event.inputs.ref }}"
62+
if [ -z "${REF}" ]; then
63+
REF=$(git tag --sort=-v:refname | head -n1)
64+
fi
65+
echo "Generating API reference from python-sdk ref: ${REF}"
66+
git checkout "${REF}"
67+
SDK_VERSION=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
68+
echo "ref=${REF}" >> "$GITHUB_OUTPUT"
69+
echo "version=${SDK_VERSION}" >> "$GITHUB_OUTPUT"
70+
71+
- name: Install the SDK and the generator deps
72+
run: |
73+
set -euo pipefail
74+
python -m pip install --upgrade pip
75+
# Installing cldk pulls in the codeanalyzer-* backends whose models the
76+
# schema pages re-export (needed for griffe alias resolution).
77+
pip install -e ../python-sdk
78+
pip install -r scripts/requirements.txt
79+
80+
- name: Regenerate API reference markdown
81+
run: python scripts/gen_api_docs.py
82+
83+
- name: Open a PR if the reference changed
84+
uses: peter-evans/create-pull-request@v6
85+
with:
86+
token: ${{ secrets.GITHUB_TOKEN }}
87+
base: astro
88+
branch: auto/api-docs
89+
add-paths: src/content/docs/reference/python-api/**
90+
commit-message: "docs(api): sync Python API reference to python-sdk ${{ steps.sdk.outputs.version }}"
91+
title: "docs(api): sync Python API reference to python-sdk ${{ steps.sdk.outputs.version }}"
92+
body: |
93+
Automated regeneration of the Python API reference from
94+
[`python-sdk`](https://github.com/codellm-devkit/python-sdk) ref
95+
`${{ steps.sdk.outputs.ref }}` (version `${{ steps.sdk.outputs.version }}`).
96+
97+
Generated by `scripts/gen_api_docs.py` (griffe). Authored intros above the
98+
`CLDK:API:START` markers are preserved; only the generated symbol
99+
reference changed. Review the diff and merge to ship.
100+
labels: documentation, automated
101+
delete-branch: true

‎astro.config.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,7 @@ export default defineConfig({
187187
{ label: "Core (CLDK)", slug: "reference/python-api/core", attrs: { "data-cldk-icon": "layers-16" } },
188188
{ label: "Python analysis", slug: "reference/python-api/python", attrs: { "data-cldk-icon": "python" } },
189189
{ label: "Java analysis", slug: "reference/python-api/java", attrs: { "data-cldk-icon": "java" } },
190+
{ label: "TypeScript analysis", slug: "reference/python-api/typescript", attrs: { "data-cldk-icon": "typescript" } },
190191
],
191192
},
192193
{

‎scripts/gen_api_docs.py‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,17 @@ def strip_emdashes(text: str) -> str:
8181
("Schema", "cldk.models.python"),
8282
],
8383
},
84+
{
85+
"file": "typescript.md",
86+
"title": "TypeScript API",
87+
"description": "Program analysis for TypeScript and related data models.",
88+
"sections": [
89+
("Analysis", "cldk.analysis.typescript.typescript_analysis"),
90+
("Schema", "cldk.models.typescript"),
91+
],
92+
},
8493
# NOTE: C analysis is intentionally omitted for now; it will return alongside
85-
# Go, TypeScript, and Rust. Re-add a PAGES entry + a sidebar item to restore it.
94+
# Go and Rust. Re-add a PAGES entry + a sidebar item to restore it.
8695
]
8796

8897

‎src/content/docs/backends/codeanalyzer-python.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -245,8 +245,8 @@ A call to `CLDK.python(project_path="my_pkg")` in the Python SDK proceeds as fol
245245
- `get_symbol_table() → Dict[str, PyModule]`
246246
- `get_classes() → Dict[str, PyClass]`
247247
- `get_call_graph() → networkx.DiGraph`
248-
- `get_callers(target_class, target_method) → List[Tuple[str, PyCallable]]`
249-
- `get_callees(source_callable) → List[PyCallable]`
248+
- `get_callers(target_class_name, target_method_declaration) → Dict`
249+
- `get_callees(source_class_name, source_method_declaration) → Dict`
250250

251251
<Tabs syncKey="lang">
252252
<TabItem label="Direct SDK usage">

‎src/content/docs/reference/python-api/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@ CLDK?](/what-is-cldk/), or the [Quickstart](/quickstart/).
2727
- **[Core (CLDK)](/reference/python-api/core/)**, the factory: the per-language `CLDK.java()`, `CLDK.python()`, `CLDK.typescript()`, and `CLDK.c()` entry points.
2828
- **[Python analysis](/reference/python-api/python/)**: symbol table and call graph via Jedi + optional CodeQL.
2929
- **[Java analysis](/reference/python-api/java/)**, the most complete analyzer: symbol table, call graph, subclasses/interfaces, CRUD.
30+
- **[TypeScript analysis](/reference/python-api/typescript/)** <span title="beta">(beta)</span>: symbol table, call graph, interfaces/enums/decorators; entrypoint detection is still in progress.
3031

31-
TypeScript is available in beta through `CLDK.typescript()` (symbol table and call graph; entrypoint detection is still in progress). Go, Rust, and C are on the way.
32+
Go, Rust, and C are on the way.
3233

3334
For runnable patterns rather than symbol lists, see [Common
3435
tasks](/guides/common-tasks/) and the [cocoa](/cocoa/).

0 commit comments

Comments
 (0)