Generate SDK API references from public source (#233)

* feat(docs): generate SDK API references

* fix(docs): render API defaults correctly

* docs: align SDK release labels with published versions

Author: linfangw

.github/workflows/contract-tests.yml

@@ -204,8 +204,8 @@ jobs:
       - name: Lint python-sdk (ruff)
         working-directory: packages/python-sdk
         run: |
-          uv run --extra dev ruff check qveris tests examples
-          uv run --extra dev ruff format --check qveris tests examples
+          uv run --extra dev ruff check qveris tests examples docs-api
+          uv run --extra dev ruff format --check qveris tests examples docs-api
 
   coverage:
     runs-on: ubuntu-latest

.github/workflows/docs-check.yml

@@ -9,6 +9,15 @@ on:
       - "docs/en-US/**"
       - "docs/zh-CN/**"
       - "docs/cn/**"
+      - "packages/js-sdk/src/**"
+      - "packages/js-sdk/docs-api/**"
+      - "packages/js-sdk/typedoc.json"
+      - "packages/js-sdk/package.json"
+      - "packages/js-sdk/package-lock.json"
+      - "packages/python-sdk/qveris/**"
+      - "packages/python-sdk/docs-api/**"
+      - "packages/python-sdk/pyproject.toml"
+      - "packages/python-sdk/uv.lock"
       - "scripts/check-doc-locales.mjs"
       - ".github/workflows/docs-check.yml"
   push:
@@ -18,13 +27,47 @@ on:
       - "docs/en-US/**"
       - "docs/zh-CN/**"
       - "docs/cn/**"
+      - "packages/js-sdk/src/**"
+      - "packages/js-sdk/docs-api/**"
+      - "packages/js-sdk/typedoc.json"
+      - "packages/js-sdk/package.json"
+      - "packages/js-sdk/package-lock.json"
+      - "packages/python-sdk/qveris/**"
+      - "packages/python-sdk/docs-api/**"
+      - "packages/python-sdk/pyproject.toml"
+      - "packages/python-sdk/uv.lock"
       - "scripts/check-doc-locales.mjs"
       - ".github/workflows/docs-check.yml"
 
 permissions:
   contents: read
 
 jobs:
+  api-reference:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: packages/js-sdk/package-lock.json
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: packages/python-sdk/uv.lock
+      - name: Generate TypeScript API reference
+        working-directory: packages/js-sdk
+        run: npm ci && npm run docs:generate
+      - name: Generate Python API reference
+        working-directory: packages/python-sdk
+        run: uv run --extra dev python docs-api/generate.py
+      - name: Check generated reference drift
+        run: git diff --exit-code -- docs/en-US/js-sdk-api.md docs/zh-CN/js-sdk-api.md docs/en-US/python-sdk-api.md docs/zh-CN/python-sdk-api.md
+
   locales:
     runs-on: ubuntu-latest
     steps:

.github/workflows/sync-docs-to-website.yml

@@ -38,9 +38,13 @@ on:
       - "docs/en-US/python-sdk.md"
       - "docs/zh-CN/python-sdk.md"
       - "docs/cn/zh-CN/python-sdk.md"
+      - "docs/en-US/python-sdk-api.md"
+      - "docs/zh-CN/python-sdk-api.md"
       - "docs/en-US/js-sdk.md"
       - "docs/zh-CN/js-sdk.md"
       - "docs/cn/zh-CN/js-sdk.md"
+      - "docs/en-US/js-sdk-api.md"
+      - "docs/zh-CN/js-sdk-api.md"
       - ".github/workflows/sync-docs-to-website.yml"
   workflow_dispatch:
 

docs/cn/zh-CN/js-sdk.md

@@ -2,7 +2,7 @@
 
 类型化的 TypeScript/JavaScript SDK，让你在自己的 Agent 和应用中发现、检查、调用并审计 10,000+ 真实已验证的 API 能力。
 
-`@qverisai/sdk` 是对 QVeris REST API（`discover`、`inspect`、`call`、`credits`、`usage`、`ledger`）的轻量类型化封装。它**零运行时依赖**——使用平台原生 `fetch`（Node.js 18+）——并与 [Python SDK](python-sdk.md) 和 [MCP 服务器](mcp-server.md) 保持一致的通信语义。
+`@qverisai/sdk` v0.4.0 是最新测试版本。它是对 QVeris REST API（`discover`、`inspect`、`call`、`credits`、`usage`、`ledger`）的轻量类型化封装，**零运行时依赖**——使用平台原生 `fetch`（Node.js 18+）——并与 [Python SDK](python-sdk.md) 和 [MCP 服务器](mcp-server.md) 保持一致的通信语义。
 
 ## 安装
 

docs/cn/zh-CN/python-sdk.md

@@ -1,6 +1,6 @@
 # QVeris Python SDK
 
-异步 Python SDK，让你在自己的 Agent 和应用中发现、检查、调用并审计 10,000+ 真实已验证的 API 能力。
+QVeris Python SDK v0.3.1 是最新测试版本。使用异步客户端，在你自己的 Agent 和应用中发现、检查、调用并审计 10,000+ 真实已验证的 API 能力。
 
 SDK 提供两种控制粒度：