Repository navigation
Site fixes ahead of the API reference work - #334
Merged
Merged
Conversation
- The page body fills its width: its Box was a flex child with no width, so it shrank to its content and the layout jumped from page to page. - Type errors in LinkCard, Tabs and remark-admonition. The controlled Tabs root drops a defaultValue that Radix ignores. - Radix Code drops Infima's leftover border and vertical-align once, in reset.css, rather than inline in CodeInline; inline code and admonitions use the outline variant. - The Management API's path is /v1/api-keys in the temporary key examples; a guide's link to the Realtime reference drops its .mdx. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Nov 2, 2026
dumitrugutu
reviewed
Nov 2, 2026
mnemitz
added a commit
that referenced
this pull request
Nov 3, 2026
**Stack 2 of 4**, splitting #331 for review. Based on #334. 1. Site fixes (#334) 2. **Management reference from the public spec** ← this PR 3. Code samples, tested against a mock 4. API reference on Speculoos ## Changes - **`spec/mp.yaml` is the public spec generated upstream** (`make public-spec` in the Management Platform repo). It's OpenAPI 3, and it already includes what this repo's old Swagger 2.0 copy added: the server, authentication (a management token everywhere; either a token or an API key on `POST /api-keys`), and the descriptions and summaries. - **`generate-mp-spec.ts` reads it as OpenAPI 3.** The spec names its own server, so the generator no longer sets `basePath`, and schema titles go on `components.schemas`. The code-sample loop goes: there were no Management samples, and PR 3 adds them through one shared injector. - **One page is renamed by the new summaries:** `post-a-new-project` → `create-a-project`, with a redirect and the link in `projects.mdx` updated. I compared the generated page list with `main`'s, and nothing else changed. The pages still render through the current OpenAPI plugin. Most of the spec diff is upstream's generated output; the review points are the generator and the redirect. ## Checked - `npm run build` passes, with no broken links. - The request schemas are in the generated pages. The plugin renders them client-side, as it does on the live site. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
mnemitz
added a commit
that referenced
this pull request
Nov 3, 2026
**Stack 3 of 4**, splitting #331 for review. Based on #335. 1. Site fixes (#334) 2. Management reference from the public spec (#335) 3. **Code samples, tested against a mock** ← this PR 4. API reference on Speculoos ## Changes - **Samples for every operation:** JavaScript, Python and curl for Batch (previously only `/jobs`), and curl for Management (previously none). - **One injector**, `scripts/code-samples/inject.ts`, adds them to both specs as `x-codeSamples`. `generate-batch-spec.ts` and `generate-mp-spec.ts` both use it, in place of Batch's own loop. - **`npm run test:code-samples`** runs each sample against a mock built from the spec (`scripts/code-samples/mock.ts`). Requests are validated against the operation's schemas, and the mock answers with the spec's examples. JavaScript runs against `@speechmatics/batch-client`, and Python against `speechmatics-batch` through `uv`. - **An OpenAPI 3.1 copy of the Batch API for the tests:** `generate-openapi.ts` converts `static/batch.yaml` with `swagger2openapi`, then applies `spec/batch.overlay.yaml` (an OpenAPI Overlay 1.0). The overlay adds a success example per operation and what Swagger 2.0 can't express, such as the multipart `config` part being a `JobConfig`. An action that matches nothing fails the build, so an upstream rename can't silently drop a patch. In PR 4 the reference renders from this same copy. - **CI:** the `Code samples` workflow runs the tests on changes to the specs, samples or harness. It has a read-only token and no secrets, as pull requests from forks get anyway. ## Checked - `npm run test:code-samples`: all 24 samples pass. - `npm run build` passes, with no broken links. - The samples are in `static/batch.yaml` and `static/mp-api.yaml`, under the same language labels as today. The plugin renders them client-side, and I haven't looked at them in a browser. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
mnemitz
added a commit
that referenced
this pull request
Nov 3, 2026
**Stack 4 of 4**, splitting #331 for review. Based on #336. 1. Site fixes (#334) 2. Management reference from the public spec (#335) 3. Code samples, tested against a mock (#336) 4. **API reference on Speculoos** ← this PR When the stack is merged, `main` matches #331's branch, minus `SPECULOOS-PLAN.md` (deleted here). ## What changes Every API reference page is rendered by [Speculoos](https://www.npmjs.com/package/@speculoos/react) (`0.1.0-alpha.1`) from IR built at build time (`npm run build:speculoos-ir`, wired into `start` and `build`). `scripts/generate-speculoos-pages.ts` writes one page per REST operation or WebSocket channel into gitignored directories, which the sidebar lists with `autogenerated`. A page's own prose, which the spec can't express (handshake responses, how a connection closes), lives in partials beside the pages. **Specs** - **Realtime** is rewritten as canonical AsyncAPI 3, with its authentication and WebSocket handshake declared. **Agent STT** is generated from it plus its overlay. - **Batch** renders from the OpenAPI 3.1 copy the code-sample tests already read (#336). **Management** renders from the public spec (#335). **Rendering** (`src/components/Speculoos/`) - `site.tsx`: how this site renders Speculoos. That's the Radix Themes map, with the site's Markdown, the sidebar's badge colours, and types expanded where they're used. - `SessionPanel.tsx`: a channel's session as a compact sequence diagram beside the reference, with each message linking to its section and showing its example on hover. Below `lg` it comes first, collapsed. - `OperationPanel.tsx`: an operation's code samples, then its examples, each labelled by its status's description ("400 Bad request"). - `Schema.tsx`: `<Schema>` puts the same field tables in guides, headed by the type's name and a link to where the reference uses it. `open` opens one field among the rest. The Batch and Realtime guides use it in place of the old `SchemaNode` and AsyncAPI loader. - The site's Markdown component moves to `src/components/Markdown`, on `react-markdown` 10 with `remark-gfm` 4 and `rehype-raw` 7. **Removed:** the OpenAPI plugin and theme, its templates and the sidebar filter for Batch paths, the `Schema`/`SchemaItem` theme components, the AsyncAPI and OpenAPI schema loaders, and the old WebSocket pages with their generator. ## Worth reviewing - **Redirects:** the Batch and Management info pages, the removed Batch log endpoint and `post-a-new-project` (from #335) are all in `redirects.json` / `vercel.json`. - **Anchors change:** message anchors are kebab-case now (`#startrecognition` → `#start-recognition`). In-repo links are updated, but external deep links to the old anchors will land at the top of the page; redirects can't cover fragments. - **CI builds from a clean checkout:** partials and `src/generated` are produced by the build, not committed. - **Speculoos is an alpha** from npm. `npm run speculoos:local` tries local packs of the Speculoos repo. ## Checked - `npm run build` passes, with no broken links. - `tsc` passes once the build has generated `src/generated`. - `npm run test:code-samples`: all 24 samples pass. Closes #331 once the stack lands. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This branch was successfully deployed
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
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.
Stack 1 of 4, splitting #331 (the Speculoos pilot) for review. Each PR builds on the one before it:
This one is independent of the rest and can merge first.
Changes
Boxwas a flex child with no width, so it shrank to its content: most Management pages and/api-refmeasured 808–945px, and the layout jumped from page to page. Every docs page is now 1000px.LinkCard,Tabsandremark-admonition. The controlledTabsroot drops adefaultValuethat Docusaurus allows to benulland Radix ignores anyway.Code: Infima's leftoverborderandvertical-alignare unset once inreset.css, rather than inline inCodeInline. Inline code and admonitions use theoutlinevariant./v1/api-keys, the Management API's path. A guide's link to the Realtime reference drops its.mdxsuffix.main's othertscerrors are in the OpenAPI theme and the WebSocket page generator, which PR 4 removes.Checked
npm run buildpasses, with no broken links.🤖 Generated with Claude Code