Skip to content

Commit ab903e0

Browse files
committed
docs(sdk): add the generated platform SDK reference and its sync
Add the Platform SDK Reference group to the SDK tab: 34 pages generated by future-agi/futureagi-sdk from its API contract (an overview, one page per resource with examples, signatures, parameters and returns, and a models table per area). The pages are never edited here. scripts/sync-sdk-reference.mjs copies the pages and the sidebar group from an SDK checkout and checks nav/page parity; .github/workflows/sdk-reference-sync.yml runs it weekly, on an SDK release dispatch or by hand, and opens a PR against main. audit-links.mjs now audits the generated group too. The ParamField styles move to a shared stylesheet so ResponseField renders styled on its own.
1 parent 91380fd commit ab903e0

42 files changed

Lines changed: 11914 additions & 95 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Refreshes the platform SDK reference (src/pages/docs/sdk/reference) from the SDK
2+
# repository's generated pages and opens a PR against main. Run it by hand for a given SDK
3+
# ref, let the SDK repository dispatch it on a release, or rely on the weekly run.
4+
name: sdk-reference-sync
5+
6+
on:
7+
workflow_dispatch:
8+
inputs:
9+
sdk_ref:
10+
description: futureagi-sdk ref to sync from (branch, tag or SHA)
11+
default: dev
12+
repository_dispatch:
13+
types: [sdk-release] # client_payload.ref: the SDK ref to sync from
14+
schedule:
15+
- cron: '0 6 * * 1' # Mondays 06:00 UTC, from the SDK's dev branch
16+
17+
permissions:
18+
contents: write
19+
pull-requests: write
20+
21+
jobs:
22+
sync:
23+
runs-on: ubuntu-latest
24+
timeout-minutes: 10
25+
steps:
26+
# App token (not GITHUB_TOKEN): the org forbids Actions from creating PRs
27+
# with GITHUB_TOKEN, and App-minted tokens are exempt. Scoped to this repo.
28+
- uses: actions/create-github-app-token@v2
29+
id: app-token
30+
with:
31+
app-id: ${{ secrets.RELEASE_BOT_APP_ID }}
32+
private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
33+
- uses: actions/checkout@v4
34+
with:
35+
ref: main
36+
token: ${{ steps.app-token.outputs.token }}
37+
- name: Resolve the SDK ref
38+
id: ref
39+
env:
40+
INPUT_REF: ${{ inputs.sdk_ref }}
41+
DISPATCH_REF: ${{ github.event.client_payload.ref }}
42+
run: echo "ref=${INPUT_REF:-${DISPATCH_REF:-dev}}" >> "$GITHUB_OUTPUT"
43+
- name: Check out the generated reference from the SDK repository
44+
uses: actions/checkout@v4
45+
with:
46+
repository: future-agi/futureagi-sdk
47+
ref: ${{ steps.ref.outputs.ref }}
48+
path: .sdk
49+
sparse-checkout: docs/sdk-reference
50+
persist-credentials: false
51+
- uses: actions/setup-node@v4
52+
with:
53+
node-version: 20
54+
- name: Sync the pages and the sidebar group
55+
run: node scripts/sync-sdk-reference.mjs --from .sdk
56+
- name: Check nav and content links
57+
run: node scripts/audit-links.mjs
58+
- name: Open PR
59+
env:
60+
GH_TOKEN: ${{ steps.app-token.outputs.token }}
61+
SDK_REF: ${{ steps.ref.outputs.ref }}
62+
run: |
63+
set -eu
64+
if git diff --quiet -- src/pages/docs/sdk/reference src/lib/sdk-reference.mjs; then
65+
echo "reference already current"; exit 0
66+
fi
67+
sha=$(git -C .sdk rev-parse --short HEAD)
68+
branch="chore/sdk-reference-${sha}"
69+
git config user.name "futureagi-release-bot"
70+
git config user.email "[email protected]"
71+
git switch -c "$branch"
72+
git add src/pages/docs/sdk/reference src/lib/sdk-reference.mjs
73+
git commit -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@${sha}"
74+
git push origin "$branch"
75+
gh pr create --base main --head "$branch" \
76+
--title "docs(sdk): platform SDK reference from futureagi-sdk@${sha}" \
77+
--body "Generated pages from [future-agi/futureagi-sdk@${sha}](https://github.com/future-agi/futureagi-sdk/tree/${sha}/docs/sdk-reference) (ref \`${SDK_REF}\`), copied by \`scripts/sync-sdk-reference.mjs\`. Do not edit the pages here: fix the generator in the SDK repository and re-run the sync."

‎scripts/audit-links.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import fs from 'fs';
1515
import path from 'path';
1616
import { fileURLToPath } from 'url';
1717
import { integrationNavigation } from '../src/lib/integrations.mjs';
18+
import { sdkReferenceNavigation } from '../src/lib/sdk-reference.mjs';
1819

1920
const __dirname = path.dirname(fileURLToPath(import.meta.url));
2021
const ROOT = path.resolve(__dirname, '..');
@@ -67,6 +68,7 @@ function addCatalogLinks(items) {
6768
}
6869
}
6970
addCatalogLinks(integrationNavigation);
71+
addCatalogLinks(sdkReferenceNavigation.items);
7072

7173
// ── 3. Extract all internal links from MDX files ──────────────
7274
function findMdxFiles(dir) {

‎scripts/sync-sdk-reference.mjs‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
// @ts-check
2+
/**
3+
* Copy the generated platform SDK reference out of a futureagi-sdk checkout.
4+
*
5+
* node scripts/sync-sdk-reference.mjs --from ../futureagi-sdk
6+
*
7+
* The SDK repository generates `docs/sdk-reference/` (one MDX page per resource, an
8+
* overview, and `navigation.json`) from its API contract with `python sdkgen/generate.py`.
9+
* This script replaces `src/pages/docs/sdk/reference/` with those pages and rewrites
10+
* `src/lib/sdk-reference.mjs`, the sidebar group `navigation.ts` imports. Never edit the
11+
* copied pages by hand: fix the generator in the SDK repository and sync again.
12+
* `.github/workflows/sdk-reference-sync.yml` runs this and opens a PR.
13+
*/
14+
import fs from 'node:fs';
15+
import path from 'node:path';
16+
import { fileURLToPath } from 'node:url';
17+
18+
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
19+
const PAGES_DIR = path.join(ROOT, 'src/pages/docs/sdk/reference');
20+
const NAV_FILE = path.join(ROOT, 'src/lib/sdk-reference.mjs');
21+
22+
const args = process.argv.slice(2);
23+
const fromIndex = args.indexOf('--from');
24+
if (fromIndex === -1 || !args[fromIndex + 1]) {
25+
console.error('usage: node scripts/sync-sdk-reference.mjs --from <path to a futureagi-sdk checkout>');
26+
process.exit(2);
27+
}
28+
const source = path.resolve(args[fromIndex + 1], 'docs/sdk-reference');
29+
const navSource = path.join(source, 'navigation.json');
30+
if (!fs.existsSync(path.join(source, 'index.mdx')) || !fs.existsSync(navSource)) {
31+
console.error(`${source} does not hold a generated reference (index.mdx + navigation.json); run python sdkgen/generate.py in the SDK checkout first`);
32+
process.exit(1);
33+
}
34+
35+
/** @type {{group: string, icon?: string, items: {title: string, href?: string, items?: {title: string, href: string}[]}[]}} */
36+
const nav = JSON.parse(fs.readFileSync(navSource, 'utf-8'));
37+
const pages = fs.readdirSync(source).filter((name) => name.endsWith('.mdx')).sort();
38+
39+
// Every nav item must have a page and every page a nav item, or the sidebar and the site drift.
40+
/** @param {{href?: string, items?: any[]}[]} items */
41+
function* walk(items) {
42+
for (const item of items) {
43+
if (item.href) yield item.href;
44+
if (item.items) yield* walk(item.items);
45+
}
46+
}
47+
const hrefs = new Set(walk(nav.items));
48+
for (const page of pages) {
49+
const href = page === 'index.mdx' ? '/docs/sdk/reference' : `/docs/sdk/reference/${page.replace(/\.mdx$/, '')}`;
50+
if (!hrefs.has(href)) {
51+
console.error(`${page} is not in navigation.json`);
52+
process.exit(1);
53+
}
54+
hrefs.delete(href);
55+
}
56+
if (hrefs.size) {
57+
console.error(`navigation.json lists pages that do not exist: ${[...hrefs].join(', ')}`);
58+
process.exit(1);
59+
}
60+
61+
fs.mkdirSync(PAGES_DIR, { recursive: true });
62+
let removed = 0;
63+
for (const name of fs.readdirSync(PAGES_DIR)) {
64+
if (name.endsWith('.mdx') && !pages.includes(name)) {
65+
fs.unlinkSync(path.join(PAGES_DIR, name));
66+
removed++;
67+
}
68+
}
69+
for (const page of pages) {
70+
fs.copyFileSync(path.join(source, page), path.join(PAGES_DIR, page));
71+
}
72+
73+
const navModule = `// @ts-check
74+
/**
75+
* Sidebar group for the platform SDK reference. Generated by
76+
* scripts/sync-sdk-reference.mjs from the SDK repository's docs/sdk-reference/navigation.json;
77+
* do not edit. navigation.ts places it in the SDK tab and scripts/audit-links.mjs audits it.
78+
*
79+
* @type {{group: string, icon?: string, items: ReadonlyArray<{title: string, href?: string, items?: ReadonlyArray<{title: string, href: string}>}>}}
80+
*/
81+
export const sdkReferenceNavigation = ${JSON.stringify(nav, null, 2)};
82+
`;
83+
fs.writeFileSync(NAV_FILE, navModule);
84+
85+
console.log(`sdk reference: ${pages.length} pages copied, ${removed} stale removed, ${[...walk(nav.items)].length} nav links`);

‎src/components/docs/ParamField.astro‎

Lines changed: 2 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
* The name of the evaluation group.
1212
* </ParamField>
1313
*/
14+
import '../../styles/fapi-param.css';
15+
1416
interface Props {
1517
path?: string;
1618
query?: string;
@@ -61,98 +63,3 @@ const paramKind = path ? 'path' : query ? 'query' : body ? 'body' : header ? 'he
6163
)}
6264
</div>
6365

64-
<style is:global>
65-
.fapi-param {
66-
padding: 16px 0;
67-
border-bottom: 1px solid var(--color-border-subtle);
68-
}
69-
.fapi-param:last-child { border-bottom: none; }
70-
71-
.fapi-param-header {
72-
display: inline-flex;
73-
align-items: center;
74-
gap: 8px;
75-
flex-wrap: wrap;
76-
max-width: 100%;
77-
min-width: 0;
78-
}
79-
.fapi-param-name {
80-
font-size: 13px;
81-
font-weight: 600;
82-
font-family: var(--font-mono);
83-
color: var(--color-text-primary);
84-
}
85-
.fapi-param-meta {
86-
display: inline-flex;
87-
align-items: center;
88-
gap: 6px;
89-
flex-wrap: wrap;
90-
}
91-
.fapi-param-type {
92-
font-size: 12px;
93-
font-family: var(--font-mono);
94-
color: #71717a;
95-
}
96-
.fapi-param-optional {
97-
font-size: 12px;
98-
color: #71717a;
99-
}
100-
.fapi-param-required {
101-
font-size: 11px;
102-
font-weight: 600;
103-
color: #f87171;
104-
text-transform: uppercase;
105-
letter-spacing: 0.3px;
106-
}
107-
.fapi-param-constraint {
108-
font-size: 11px;
109-
font-family: var(--font-mono);
110-
color: #71717a;
111-
padding: 1px 6px;
112-
background: rgba(255,255,255,0.04);
113-
border: 1px solid rgba(255,255,255,0.08);
114-
border-radius: 4px;
115-
}
116-
.fapi-param-default {
117-
font-size: 12px;
118-
color: #71717a;
119-
}
120-
.fapi-param-default code {
121-
font-size: 11px;
122-
padding: 1px 4px;
123-
background: rgba(255,255,255,0.04);
124-
border-radius: 3px;
125-
}
126-
.fapi-param-desc {
127-
font-size: 13px;
128-
color: #a1a1aa;
129-
line-height: 1.6;
130-
margin-top: 4px;
131-
}
132-
.fapi-param-desc p { margin: 0; }
133-
134-
/* Enum values */
135-
.fapi-param-enum {
136-
margin-top: 8px;
137-
}
138-
.fapi-param-enum-label {
139-
font-size: 12px;
140-
color: #71717a;
141-
margin-bottom: 4px;
142-
display: block;
143-
}
144-
.fapi-param-enum-values {
145-
display: flex;
146-
flex-wrap: wrap;
147-
gap: 4px;
148-
}
149-
.fapi-param-enum-val {
150-
font-size: 11px;
151-
font-family: var(--font-mono);
152-
padding: 2px 8px;
153-
background: rgba(255,255,255,0.04);
154-
border: 1px solid rgba(255,255,255,0.08);
155-
border-radius: 4px;
156-
color: #a1a1aa;
157-
}
158-
</style>

‎src/components/docs/ResponseField.astro‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
* Unique identifier for the resource.
88
* </ResponseField>
99
*/
10+
import '../../styles/fapi-param.css';
11+
1012
interface Props {
1113
name: string;
1214
type?: string;

‎src/lib/navigation.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
*/
88

99
import { integrationNavigation } from './integrations.mjs';
10+
import { sdkReferenceNavigation } from './sdk-reference.mjs';
1011

1112
export interface NavItem {
1213
title: string;
@@ -1148,6 +1149,8 @@ export const tabNavigation: NavTab[] = [
11481149
},
11491150
]
11501151
},
1152+
// Generated from the SDK repository (scripts/sync-sdk-reference.mjs); one page per resource.
1153+
sdkReferenceNavigation,
11511154
{
11521155
group: 'Evaluation',
11531156
icon: 'chart',

0 commit comments

Comments
 (0)