feat(docs): add layout.api-reference-layout to docs.yml - #17377
feat(docs): add layout.api-reference-layout to docs.yml#17377devin-ai-integration[bot] wants to merge 1 commit into
Conversation
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![nitpickybot[bot]](https://avatars.githubusercontent.com/in/2901896?s=60&v=4){kind=small}
There was a problem hiding this comment.
AI Review Summary
Purely additive plumbing for a new layout.api-reference-layout enum, mirroring the existing changelog-layout pattern: docs-yml definition, zod raw schema, generated SDK/serializers, JSON schemas, and a passthrough in convertLayoutConfig. Generated artifacts look consistent with the definition (both docs-yml.schema.json copies are in sync). No functional bugs spotted; only a note about the widening as unknown as escape hatch.
- 🔵 1 suggestion(s)
| // Passed through as-is (no default): omitted renders the indented | ||
| // connector-line tree, "cards" renders the legacy nested cards. Resolved | ||
| // by the fern-platform companion PR. Part of the `as unknown as` cast | ||
| // below until the published FDR SDK adds `apiReferenceLayout`. | ||
| apiReferenceLayout: layout.apiReferenceLayout, |
There was a problem hiding this comment.
🔵 suggestion
This is now the third field smuggled through the as unknown as ParsedDocsConfiguration["layout"] cast, which means a typo in apiReferenceLayout (or a mismatch with the eventual FDR field name) compiles silently and fails only at runtime in the platform. Consider a narrow local type (e.g. type PendingLayoutFields = { changelogLayout?: ...; apiReferenceLayout?: ...; showNavAvailabilityBadges?: boolean }) spread into the cast so at least the pending keys are typed, and confirm the downstream docs-registration path forwards unknown layout keys rather than mapping fields explicitly.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Docs Generation Benchmark ResultsComparing PR branch against median of 5 nightly run(s) on
Docs generation runs |
SDK Generation Benchmark ResultsComparing PR branch against median of 5 nightly run(s) on Full benchmark table (click to expand)
main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via |
1 participant
Description
Adds a
layout.api-reference-layoutkey todocs.ymlso sites can choose how nested object fields render in the API Reference:indented— nested levels render as an indented connector-line tree with a path breadcrumb per level.cards— the legacy bordered-card nesting.The CLI only validates and forwards the value; the default and the rendering live in fern-platform (https://github.com/fern-api/fern-platform/pull/13441). Follows
changelog-layout(fd5604f) exactly: new enum in the docs-yml definition, the raw-schema key, and passthrough inconvertLayoutConfig, which stays inside the existingas unknown ascast until the published FDR SDK carriesapiReferenceLayout.// parseDocsConfiguration.ts convertLayoutConfig + apiReferenceLayout: layout.apiReferenceLayout, } as unknown as docsYml.ParsedDocsConfiguration["layout"];Changes Made
fern/apis/docs-yml/definition/docs.yml:ApiReferenceLayoutenum + optionalapi-reference-layoutonLayoutConfig.DocsYmlSchemas.ts: zodApiReferenceLayout,"api-reference-layout"on the rawLayoutConfig.parseDocsConfiguration.ts: passthrough with no default (omitted means platform default).fern generate --local --api docs-yml, JSON schemas viapnpm docs-yml:jsonschemaandpnpm fern-yml:jsonschema. The generatedApiReferenceLayout.tsfiles came out byte-identical in shape toChangelogLayout.ts.feat) underchanges/unreleased/.Testing
pnpm compile— 160/160 tasks pass.pnpm turbo run test --filter @fern-api/configuration --filter @fern-api/configuration-loader --filter @fern-api/workspace-loader— 33/33 tasks, all tests pass.pnpm lint:biome,pnpm format— clean, no fixes applied.api-reference-layoutlanded in all three generated JSON schemas (docs-yml.schema.json,packages/cli/workspace/loader/src/docs-yml.schema.json,fern-yml.schema.json).changelog-layout, which has no dedicated test (the key is covered by schema validation).Docs: fern-api/docs#6596
Link to Devin session: https://app.devin.ai/sessions/1f176e5bc4fc49f480e0be1183283042