feat: automated developer docs site (TypeDoc + Starlight + CI)#4
Merged
Conversation
Astro Starlight site under docs-site/ targeting docs.appos.space: - Three starlight-typedoc instances (one per SDK package) generate the API Reference from packages/*/src/index.ts at build time into src/content/docs/api/ (gitignored — regenerated every build). Single-entry-point mode per package is deliberate: multi-entry mode deletes per-module index pages and leaves broken Modules links. - tsconfig.typedoc.json maps @appos.space/plugin-types to the source entry so view-builders documents without a prior package build. - Hand-written Getting Started guides seeded from the repo READMEs (installation, first plugin, package overview) + manifest overview. - Sidebar: Getting Started / API Reference / Manifest & Permissions / Extension Points. /api redirects to the plugin-types index.
scripts/generate-docs-data.mjs extracts from the in-repo sources of
truth (schemas/plugin-v1.json, schemas/constraints.json,
packages/plugin-types/src/{permissions,core}.ts) and emits committed,
deterministic pages:
- reference/namespaces.md — all 43 context.* namespaces from
PluginContext, split legacy tier vs core-plugin tier
- manifest/reference.md — every plugin.json field from the JSON Schema
- manifest/permission-scopes.md — 135 canonical scopes grouped by
subsystem + dynamic oauth.* family + 5 legacy aliases, with a
cross-check between permissions.ts and constraints.json that surfaces
drift in the page
- manifest/limits.md — runtime quotas, build constraints, view tokens
- extension-points/index.md — extensions[] mechanism + contribution
surfaces derived from contributor permission scopes; TODO stub for
the host-owned per-point payload schemas (not machine-readable here)
- extension-points/event-topics.md — typed-bus mechanism; TODO stub for
the host-owned topic catalog (use events.listTopics() at runtime)
--check mode is the CI drift gate: regenerates in-memory, byte-compares
against committed files, and verifies the recorded SHA-256 input hash
(generated-docs.hash). Fails when type declarations change without the
generated docs being regenerated.
scripts/generate-llms-txt.mjs runs after astro build and emits into dist/ per the llms.txt convention (llmstxt.org): - llms.txt — site summary + grouped index of every page with URLs - llms-full.txt — full corpus: raw markdown of every docs page (including the TypeDoc-generated API reference), the SDK TypeScript sources from all three packages, and the manifest schemas Wired into npm run build as the final step.
.github/workflows/docs.yml — on push to main, PRs touching docs-site/ | packages/ | schemas/, and manual dispatch: 1. npm ci in docs-site 2. Drift gate: npm run check-drift fails the build when the committed generated docs are stale vs the current type declarations/schemas (byte-compare + SHA-256 input-hash check) 3. Full site build (TypeDoc API reference + llms.txt) and artifact upload The Cloudflare Pages deploy job (target docs.appos.space, project appos-docs) is committed as a commented stub: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must be added as repo secrets before enabling. No credentials are fabricated or committed.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 84b03afbf4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- Rewrite first-plugin quick-start against real fileOps/registerPanel surface (ctx.fs/ui.render + 3 more invented APIs) - Fix packages.md snippets: button() options, callable prefix-keyed action router, real ctx.ui.openEditor - Require no-op deactivate in installation guide per schemas/constraints.json requiredExports - Extension-points generator: segment-boundary contributor-verb regex (adds palette.contribute.scope, webhook.route.register.unsigned)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b16ae5af6d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- installation.md: esbuild in install block, npx build one-liner, remove fictional global-types path (verified in fresh project) - first-plugin.md: (globalThis as any) casts per host skill-doc idiom (strict-tsc verified) - validate-schema.mjs: positional manifest support so the documented command actually validates the given file (also repairs manifest/index.md's invocation) - docs.yml: un-stub Cloudflare Pages deploy (project appos-docs live, repo secrets set)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3d3d57a894
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- README: replace stale 'deploy stubbed' bullet with Deployment section (job enabled, secrets configured, docs.appos.space live) - first-plugin: npx esbuild build command matching installation.md idiom (scratch-verified)
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated developer-documentation site for the plugin SDK, targeting docs.appos.space. Everything lives in a new top-level
docs-site/directory plus one CI workflow.Pipeline
starlight-typedocinstances (one per package:plugin-types,view-builders,plugin-utils) run TypeDoc + typedoc-plugin-markdown overpackages/*/src/index.tsduringastro build. Output lands insrc/content/docs/api/(gitignored, regenerated every build). One instance per package is deliberate: starlight-typedoc's multi-entry mode deletes per-module index pages and leaves broken "Modules" links.tsconfig.typedoc.jsonmaps@appos.space/plugin-typesto the source entry soview-buildersdocuments without a prior package build.docs-site/scripts/generate-docs-data.mjsextracts from the in-repo sources of truth (schemas/plugin-v1.json,schemas/constraints.json,packages/plugin-types/src/{permissions,core}.ts) and emits committed, deterministic pages: namespace map (all 43context.*namespaces), manifest field reference, permission-scope catalog (135 canonical scopes grouped by subsystem +oauth.*family + 5 legacy aliases, with cross-source drift surfacing), runtime limits, and extension-point contribution surfaces./apiredirect.generate-llms-txt.mjsruns post-build and emitsdist/llms.txt(index) +dist/llms-full.txt(full corpus: every page incl. TypeDoc output + the SDK type sources + schemas), per llmstxt.org..github/workflows/docs.yml) — on push to main / relevant PRs:npm ci→ drift gate (npm run check-driftbyte-compares committed generated pages against a fresh regeneration and verifies the SHA-256 input hash ingenerated-docs.hash; fails when the type declarations changed without regenerating) → full build → artifact upload.What's stubbed
appos-docs, target docs.appos.space). RequiresCLOUDFLARE_API_TOKEN+CLOUDFLARE_ACCOUNT_IDrepo secrets before enabling; no credentials fabricated.events.listTopics()).Verification
cd docs-site && npm install && npm run build→ 224 pages, exit 0, zero TypeDoc/Astro warnings.permissions.ts→check-driftexits 1; restore → exits 0.Local dev