From ecd443540e87ddaaae122b5a0d6c1ddcaac1813c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 2 Feb 2026 23:57:52 +0000 Subject: [PATCH 01/13] Initial plan From b002ac5888ef783b38f347b0dd558bee5e0de980 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Feb 2026 00:00:58 +0000 Subject: [PATCH 02/13] Add usage instructions and experimental warning to HTTP typekits documentation Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../libraries/http/reference/typekits.mdx | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index dbb44a734a6..5d5e15f811b 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -2,7 +2,33 @@ title: "[API] Typekits" --- -import { Badge } from '@astrojs/starlight/components'; +import { Badge, Aside } from '@astrojs/starlight/components'; + + + +## Usage + +To use HTTP typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: + +```ts +import "@typespec/http/experimental/typekit"; +import { $ } from "@typespec/compiler/typekit"; +``` + +The first import registers the HTTP-specific typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. + +### Example + +```ts +import { getHttpOperation } from "@typespec/http"; +import { $ } from "@typespec/compiler/typekit"; +import "@typespec/http/experimental/typekit"; + +const [httpOperation] = getHttpOperation(program, operation); +const responses = $(program).httpOperation.flattenResponses(httpOperation); +``` ## model From f6c5749be8fa772b74e0c6e6336f4f5a1519cad4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Feb 2026 02:11:21 +0000 Subject: [PATCH 03/13] Merge latest main to fix website build issues Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../libraries/http/reference/typekits.mdx | 28 +------------------ 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index 5d5e15f811b..dbb44a734a6 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -2,33 +2,7 @@ title: "[API] Typekits" --- -import { Badge, Aside } from '@astrojs/starlight/components'; - - - -## Usage - -To use HTTP typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: - -```ts -import "@typespec/http/experimental/typekit"; -import { $ } from "@typespec/compiler/typekit"; -``` - -The first import registers the HTTP-specific typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. - -### Example - -```ts -import { getHttpOperation } from "@typespec/http"; -import { $ } from "@typespec/compiler/typekit"; -import "@typespec/http/experimental/typekit"; - -const [httpOperation] = getHttpOperation(program, operation); -const responses = $(program).httpOperation.flattenResponses(httpOperation); -``` +import { Badge } from '@astrojs/starlight/components'; ## model From aa2b62320948f95c9967a6a9834de52252a1aeee Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Feb 2026 02:11:59 +0000 Subject: [PATCH 04/13] Revert "Merge latest main to fix website build issues" This reverts commit f6c5749be8fa772b74e0c6e6336f4f5a1519cad4. --- .../libraries/http/reference/typekits.mdx | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index dbb44a734a6..5d5e15f811b 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -2,7 +2,33 @@ title: "[API] Typekits" --- -import { Badge } from '@astrojs/starlight/components'; +import { Badge, Aside } from '@astrojs/starlight/components'; + + + +## Usage + +To use HTTP typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: + +```ts +import "@typespec/http/experimental/typekit"; +import { $ } from "@typespec/compiler/typekit"; +``` + +The first import registers the HTTP-specific typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. + +### Example + +```ts +import { getHttpOperation } from "@typespec/http"; +import { $ } from "@typespec/compiler/typekit"; +import "@typespec/http/experimental/typekit"; + +const [httpOperation] = getHttpOperation(program, operation); +const responses = $(program).httpOperation.flattenResponses(httpOperation); +``` ## model From 7b6e19e72d5468b45b4d6c37f71e682dcde3978c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 03:45:17 +0000 Subject: [PATCH 05/13] Add experimental warning and usage docs to auto-generated typekit documentation Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../src/ref-doc/components/typekits-file.tsx | 50 ++++++++++++++++++- packages/tspd/src/ref-doc/typekit-docs.ts | 21 ++++++-- .../libraries/http/reference/typekits.mdx | 4 +- .../standard-library/reference/typekits.mdx | 26 +++++++++- 4 files changed, 93 insertions(+), 8 deletions(-) diff --git a/packages/tspd/src/ref-doc/components/typekits-file.tsx b/packages/tspd/src/ref-doc/components/typekits-file.tsx index c63e8a81e1d..2b95abb8da7 100644 --- a/packages/tspd/src/ref-doc/components/typekits-file.tsx +++ b/packages/tspd/src/ref-doc/components/typekits-file.tsx @@ -12,16 +12,62 @@ import { format as prettierFormat } from "prettier"; import { TypekitCollection } from "../typekit-docs.js"; import { TypekitSection } from "./typekit-section.js"; -export function createTypekitDocs(typekit: TypekitCollection) { +export function createTypekitDocs(typekit: TypekitCollection, packageName?: string) { + const isHttpPackage = packageName === "@typespec/http"; + const experimentalImport = isHttpPackage + ? `import "@typespec/http/experimental/typekit";` + : `import "@typespec/compiler/typekit";`; + + const usageExample = isHttpPackage + ? `\`\`\`ts +import { getHttpOperation } from "@typespec/http"; +import { $ } from "@typespec/compiler/typekit"; +import "@typespec/http/experimental/typekit"; + +const [httpOperation] = getHttpOperation(program, operation); +const responses = $(program).httpOperation.flattenResponses(httpOperation); +\`\`\`` + : `\`\`\`ts +import { $ } from "@typespec/compiler/typekit"; + +// Use typekits in your code +const arrayType = $(program).array.create(stringType); +\`\`\``; + const jsxContent = ( <> {code` - import { Badge } from '@astrojs/starlight/components'; + import { Badge${typekit.isExperimental ? ", Aside" : ""} } from '@astrojs/starlight/components'; `} + {typekit.isExperimental && ( + <> + {code` + + + + ## Usage + + To use these typekits in your TypeSpec emitter or tool, you need to import the${isHttpPackage ? " experimental" : ""} typekit module: + + \`\`\`ts + ${experimentalImport} + import { $ } from "@typespec/compiler/typekit"; + \`\`\` + + The first import registers the${isHttpPackage ? " HTTP-specific" : ""} typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. + + ### Example + + ${usageExample} + `} + + )} {(x) => } diff --git a/packages/tspd/src/ref-doc/typekit-docs.ts b/packages/tspd/src/ref-doc/typekit-docs.ts index 83e63569334..bc2753eb351 100644 --- a/packages/tspd/src/ref-doc/typekit-docs.ts +++ b/packages/tspd/src/ref-doc/typekit-docs.ts @@ -15,6 +15,7 @@ import { readPackageJson } from "./utils/misc.js"; export interface TypekitCollection { namespaces: Record; + isExperimental?: boolean; } export interface TypekitNamespace { @@ -22,6 +23,7 @@ export interface TypekitNamespace { typeName: string; doc?: DocSection; entries: Record; + isExperimental?: boolean; } type TypekitEntryDoc = TypekitNamespace | TypekitFunctionDoc; @@ -72,7 +74,7 @@ export async function writeTypekitDocs(libraryPath: string, outputDir: string): if (!typekits) { return; } - const output = await createTypekitDocs(typekits); + const output = await createTypekitDocs(typekits, pkgJson.name); for (const [file, content] of Object.entries(output)) { await writeFile(joinPaths(outputDir, file), content); } @@ -87,6 +89,7 @@ async function getTypekitApi( return undefined; } const namespaces: Record = {}; + let hasExperimental = false; for (const pkgMember of api.packages[0].members) { for (const member of pkgMember.members) { if (member instanceof ApiInterface) { @@ -96,19 +99,29 @@ async function getTypekitApi( const name = (typekitTag.content.nodes[0] as any).nodes.filter( (x: DocNode) => x.kind === "PlainText", )[0].text; - const typekit: TypekitNamespace = resolveTypekit(member, [name]); + const isExperimental = + docComment?.modifierTagSet.hasTagName("@experimental") ?? false; + if (isExperimental) { + hasExperimental = true; + } + const typekit: TypekitNamespace = resolveTypekit(member, [name], isExperimental); namespaces[name] = typekit; } } } } - function resolveTypekit(iface: ApiInterface, path: string[]): TypekitNamespace { + function resolveTypekit( + iface: ApiInterface, + path: string[], + isExperimental: boolean, + ): TypekitNamespace { const typekit: TypekitNamespace = { name: path[0], typeName: iface.displayName, doc: iface.tsdocComment?.summarySection, entries: {}, + isExperimental, }; for (const member of iface.members) { if (member instanceof ApiPropertySignature) { @@ -119,6 +132,7 @@ async function getTypekitApi( typekit.entries[member.displayName] = resolveTypekit( subkit.resolvedApiItem as ApiInterface, [...path, member.displayName], + isExperimental, ); } else if (propertyReference.toString() === "@typespec/compiler!Diagnosable:type") { typekit.entries[member.displayName] = { @@ -170,5 +184,6 @@ async function getTypekitApi( return { namespaces, + isExperimental: hasExperimental, }; } diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index 5d5e15f811b..0a144f8c8be 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -5,12 +5,12 @@ title: "[API] Typekits" import { Badge, Aside } from '@astrojs/starlight/components'; ## Usage -To use HTTP typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: +To use these typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: ```ts import "@typespec/http/experimental/typekit"; diff --git a/website/src/content/docs/docs/standard-library/reference/typekits.mdx b/website/src/content/docs/docs/standard-library/reference/typekits.mdx index 93bab0a07f6..d919c35a7fb 100644 --- a/website/src/content/docs/docs/standard-library/reference/typekits.mdx +++ b/website/src/content/docs/docs/standard-library/reference/typekits.mdx @@ -2,7 +2,31 @@ title: "[API] Typekits" --- -import { Badge } from '@astrojs/starlight/components'; +import { Badge, Aside } from '@astrojs/starlight/components'; + + + +## Usage + +To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: + +```ts +import "@typespec/compiler/typekit"; +import { $ } from "@typespec/compiler/typekit"; +``` + +The first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. + +### Example + +```ts +import { $ } from "@typespec/compiler/typekit"; + +// Use typekits in your code +const arrayType = $(program).array.create(stringType); +``` ## array From 22f90fed70dce5595129623220d18268c8268aca Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 20:11:40 +0000 Subject: [PATCH 06/13] Fix formatting and add changeset for tspd Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- ...ot-fix-http-typekits-documentation-2026-2-3-20-11-24.md | 7 +++++++ packages/tspd/src/ref-doc/components/typekits-file.tsx | 2 +- packages/tspd/src/ref-doc/typekit-docs.ts | 3 +-- 3 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 .chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-20-11-24.md diff --git a/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-20-11-24.md b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-20-11-24.md new file mode 100644 index 00000000000..96f704e2289 --- /dev/null +++ b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-20-11-24.md @@ -0,0 +1,7 @@ +--- +changeKind: feature +packages: + - "@typespec/tspd" +--- + +Auto-generate experimental warnings and usage documentation for typekits \ No newline at end of file diff --git a/packages/tspd/src/ref-doc/components/typekits-file.tsx b/packages/tspd/src/ref-doc/components/typekits-file.tsx index 2b95abb8da7..845edad0e46 100644 --- a/packages/tspd/src/ref-doc/components/typekits-file.tsx +++ b/packages/tspd/src/ref-doc/components/typekits-file.tsx @@ -17,7 +17,7 @@ export function createTypekitDocs(typekit: TypekitCollection, packageName?: stri const experimentalImport = isHttpPackage ? `import "@typespec/http/experimental/typekit";` : `import "@typespec/compiler/typekit";`; - + const usageExample = isHttpPackage ? `\`\`\`ts import { getHttpOperation } from "@typespec/http"; diff --git a/packages/tspd/src/ref-doc/typekit-docs.ts b/packages/tspd/src/ref-doc/typekit-docs.ts index bc2753eb351..47facb5e20d 100644 --- a/packages/tspd/src/ref-doc/typekit-docs.ts +++ b/packages/tspd/src/ref-doc/typekit-docs.ts @@ -99,8 +99,7 @@ async function getTypekitApi( const name = (typekitTag.content.nodes[0] as any).nodes.filter( (x: DocNode) => x.kind === "PlainText", )[0].text; - const isExperimental = - docComment?.modifierTagSet.hasTagName("@experimental") ?? false; + const isExperimental = docComment?.modifierTagSet.hasTagName("@experimental") ?? false; if (isExperimental) { hasExperimental = true; } From 1bd3d39657283f8ee996506df8b92e30dcfc0077 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 20:42:40 +0000 Subject: [PATCH 07/13] Refactor to use generic @usageDoc mechanism instead of HTTP-specific special case Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../typekit/kits/http-operation.ts | 22 +++++++ .../src/ref-doc/components/typekits-file.tsx | 41 ++---------- packages/tspd/src/ref-doc/typekit-docs.ts | 63 ++++++++++++++++++- .../libraries/http/reference/typekits.mdx | 1 - .../standard-library/reference/typekits.mdx | 20 ------ 5 files changed, 87 insertions(+), 60 deletions(-) diff --git a/packages/http/src/experimental/typekit/kits/http-operation.ts b/packages/http/src/experimental/typekit/kits/http-operation.ts index 4d9b837e68f..b52d33d1ea7 100644 --- a/packages/http/src/experimental/typekit/kits/http-operation.ts +++ b/packages/http/src/experimental/typekit/kits/http-operation.ts @@ -16,6 +16,28 @@ import { * Utilities for working with HTTP operations. * @typekit httpOperation * @experimental + * @usageDoc + * ## Usage + * + * To use these typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: + * + * ```ts + * import "@typespec/http/experimental/typekit"; + * import { $ } from "@typespec/compiler/typekit"; + * ``` + * + * The first import registers the HTTP-specific typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. + * + * ### Example + * + * ```ts + * import { getHttpOperation } from "@typespec/http"; + * import { $ } from "@typespec/compiler/typekit"; + * import "@typespec/http/experimental/typekit"; + * + * const [httpOperation] = getHttpOperation(program, operation); + * const responses = $(program).httpOperation.flattenResponses(httpOperation); + * ``` */ export interface HttpOperationKit { /** diff --git a/packages/tspd/src/ref-doc/components/typekits-file.tsx b/packages/tspd/src/ref-doc/components/typekits-file.tsx index 845edad0e46..be84e664553 100644 --- a/packages/tspd/src/ref-doc/components/typekits-file.tsx +++ b/packages/tspd/src/ref-doc/components/typekits-file.tsx @@ -12,28 +12,7 @@ import { format as prettierFormat } from "prettier"; import { TypekitCollection } from "../typekit-docs.js"; import { TypekitSection } from "./typekit-section.js"; -export function createTypekitDocs(typekit: TypekitCollection, packageName?: string) { - const isHttpPackage = packageName === "@typespec/http"; - const experimentalImport = isHttpPackage - ? `import "@typespec/http/experimental/typekit";` - : `import "@typespec/compiler/typekit";`; - - const usageExample = isHttpPackage - ? `\`\`\`ts -import { getHttpOperation } from "@typespec/http"; -import { $ } from "@typespec/compiler/typekit"; -import "@typespec/http/experimental/typekit"; - -const [httpOperation] = getHttpOperation(program, operation); -const responses = $(program).httpOperation.flattenResponses(httpOperation); -\`\`\`` - : `\`\`\`ts -import { $ } from "@typespec/compiler/typekit"; - -// Use typekits in your code -const arrayType = $(program).array.create(stringType); -\`\`\``; - +export function createTypekitDocs(typekit: TypekitCollection) { const jsxContent = ( @@ -50,21 +29,11 @@ const arrayType = $(program).array.create(stringType); + `} + {typekit.usageDoc && + code` - ## Usage - - To use these typekits in your TypeSpec emitter or tool, you need to import the${isHttpPackage ? " experimental" : ""} typekit module: - - \`\`\`ts - ${experimentalImport} - import { $ } from "@typespec/compiler/typekit"; - \`\`\` - - The first import registers the${isHttpPackage ? " HTTP-specific" : ""} typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. - - ### Example - - ${usageExample} + ${typekit.usageDoc} `} )} diff --git a/packages/tspd/src/ref-doc/typekit-docs.ts b/packages/tspd/src/ref-doc/typekit-docs.ts index 47facb5e20d..b44e26462db 100644 --- a/packages/tspd/src/ref-doc/typekit-docs.ts +++ b/packages/tspd/src/ref-doc/typekit-docs.ts @@ -8,7 +8,7 @@ import { } from "@microsoft/api-extractor-model"; import { DocNode, type DocComment, type DocSection } from "@microsoft/tsdoc"; import { joinPaths, PackageJson } from "@typespec/compiler"; -import { writeFile } from "fs/promises"; +import { readdir, readFile, writeFile } from "fs/promises"; import { createApiModel } from "./api-extractor.js"; import { createTypekitDocs } from "./components/typekits-file.js"; import { readPackageJson } from "./utils/misc.js"; @@ -16,6 +16,7 @@ import { readPackageJson } from "./utils/misc.js"; export interface TypekitCollection { namespaces: Record; isExperimental?: boolean; + usageDoc?: string; } export interface TypekitNamespace { @@ -24,6 +25,7 @@ export interface TypekitNamespace { doc?: DocSection; entries: Record; isExperimental?: boolean; + usageDoc?: string; } type TypekitEntryDoc = TypekitNamespace | TypekitFunctionDoc; @@ -74,12 +76,52 @@ export async function writeTypekitDocs(libraryPath: string, outputDir: string): if (!typekits) { return; } - const output = await createTypekitDocs(typekits, pkgJson.name); + const output = await createTypekitDocs(typekits); for (const [file, content] of Object.entries(output)) { await writeFile(joinPaths(outputDir, file), content); } } +async function extractUsageDocFromLibrary(libraryPath: string): Promise { + // Look for typekit files in the library and extract @usageDoc + async function searchDirectory(dir: string): Promise { + try { + const entries = await readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = joinPaths(dir, entry.name); + if (entry.isDirectory()) { + const result = await searchDirectory(fullPath); + if (result) return result; + } else if (entry.isFile() && entry.name.endsWith(".ts")) { + const content = await readFile(fullPath, "utf-8"); + const usageMatch = content.match( + /@usageDoc\s+([\s\S]*?)(?:\n\s*\*\s*@(?:experimental|typekit)|\n\s*\*\/)/, + ); + if (usageMatch) { + return usageMatch[1] + .split("\n") + .map((line) => line.replace(/^\s*\*\s?/, "")) + .join("\n") + .trim(); + } + } + } + } catch (error) { + // Ignore errors (e.g., directory doesn't exist) + } + return undefined; + } + + // Search in src/typekit and src/experimental/typekit directories + const typekitDir = joinPaths(libraryPath, "src", "typekit"); + let result = await searchDirectory(typekitDir); + if (!result) { + const experimentalTypekitDir = joinPaths(libraryPath, "src", "experimental", "typekit"); + result = await searchDirectory(experimentalTypekitDir); + } + return result; +} + async function getTypekitApi( libraryPath: string, pkgJson: PackageJson, @@ -90,6 +132,10 @@ async function getTypekitApi( } const namespaces: Record = {}; let hasExperimental = false; + + // Extract usage documentation from the library source files once + const collectionUsageDoc = await extractUsageDocFromLibrary(libraryPath); + for (const pkgMember of api.packages[0].members) { for (const member of pkgMember.members) { if (member instanceof ApiInterface) { @@ -103,7 +149,14 @@ async function getTypekitApi( if (isExperimental) { hasExperimental = true; } - const typekit: TypekitNamespace = resolveTypekit(member, [name], isExperimental); + + // Usage doc is extracted once for the entire collection from source files + const typekit: TypekitNamespace = resolveTypekit( + member, + [name], + isExperimental, + collectionUsageDoc, + ); namespaces[name] = typekit; } } @@ -114,6 +167,7 @@ async function getTypekitApi( iface: ApiInterface, path: string[], isExperimental: boolean, + usageDoc?: string, ): TypekitNamespace { const typekit: TypekitNamespace = { name: path[0], @@ -121,6 +175,7 @@ async function getTypekitApi( doc: iface.tsdocComment?.summarySection, entries: {}, isExperimental, + usageDoc, }; for (const member of iface.members) { if (member instanceof ApiPropertySignature) { @@ -132,6 +187,7 @@ async function getTypekitApi( subkit.resolvedApiItem as ApiInterface, [...path, member.displayName], isExperimental, + undefined, // Sub-kits don't have their own usage docs ); } else if (propertyReference.toString() === "@typespec/compiler!Diagnosable:type") { typekit.entries[member.displayName] = { @@ -184,5 +240,6 @@ async function getTypekitApi( return { namespaces, isExperimental: hasExperimental, + usageDoc: collectionUsageDoc, }; } diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index 0a144f8c8be..aae47ba1aed 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -7,7 +7,6 @@ import { Badge, Aside } from '@astrojs/starlight/components'; - ## Usage To use these typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: diff --git a/website/src/content/docs/docs/standard-library/reference/typekits.mdx b/website/src/content/docs/docs/standard-library/reference/typekits.mdx index d919c35a7fb..d77f41a5fa6 100644 --- a/website/src/content/docs/docs/standard-library/reference/typekits.mdx +++ b/website/src/content/docs/docs/standard-library/reference/typekits.mdx @@ -8,26 +8,6 @@ import { Badge, Aside } from '@astrojs/starlight/components'; **Experimental Feature**: These typekits are currently experimental. The API surface is volatile and may have breaking changes without notice. Use with caution in production environments. -## Usage - -To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: - -```ts -import "@typespec/compiler/typekit"; -import { $ } from "@typespec/compiler/typekit"; -``` - -The first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. - -### Example - -```ts -import { $ } from "@typespec/compiler/typekit"; - -// Use typekits in your code -const arrayType = $(program).array.create(stringType); -``` - ## array Typekits for working with array types(Model with number indexer). From e5d439734fbace51e198f62a9dd0ca15e200bb67 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 22:21:56 +0000 Subject: [PATCH 08/13] Add changeset for @typespec/http package Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- ...ot-fix-http-typekits-documentation-2026-2-3-22-21-43.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md diff --git a/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md new file mode 100644 index 00000000000..ec8d422705d --- /dev/null +++ b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http" +--- + +Add @usageDoc JSDoc tag to HTTP typekit for auto-generated usage documentation \ No newline at end of file From 02c2ea8790d9a4b8148d6dafa0c580c83d24cef8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Mar 2026 23:02:41 +0000 Subject: [PATCH 09/13] Use TSDoc custom block for @usageDoc instead of file I/O Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- packages/tspd/src/ref-doc/api-extractor.ts | 4 ++ packages/tspd/src/ref-doc/typekit-docs.ts | 84 ++++++++++------------ 2 files changed, 43 insertions(+), 45 deletions(-) diff --git a/packages/tspd/src/ref-doc/api-extractor.ts b/packages/tspd/src/ref-doc/api-extractor.ts index e73af12bfa5..135cc336364 100644 --- a/packages/tspd/src/ref-doc/api-extractor.ts +++ b/packages/tspd/src/ref-doc/api-extractor.ts @@ -75,6 +75,10 @@ export function createApiModelFileForExport( tagName: "@typekit", syntaxKind: "block", }, + { + tagName: "@usageDoc", + syntaxKind: "block", + }, ], }), packageJsonFullPath: joinPaths(libraryPath, "package.json"), diff --git a/packages/tspd/src/ref-doc/typekit-docs.ts b/packages/tspd/src/ref-doc/typekit-docs.ts index b44e26462db..37d23ce1e85 100644 --- a/packages/tspd/src/ref-doc/typekit-docs.ts +++ b/packages/tspd/src/ref-doc/typekit-docs.ts @@ -8,7 +8,7 @@ import { } from "@microsoft/api-extractor-model"; import { DocNode, type DocComment, type DocSection } from "@microsoft/tsdoc"; import { joinPaths, PackageJson } from "@typespec/compiler"; -import { readdir, readFile, writeFile } from "fs/promises"; +import { writeFile } from "fs/promises"; import { createApiModel } from "./api-extractor.js"; import { createTypekitDocs } from "./components/typekits-file.js"; import { readPackageJson } from "./utils/misc.js"; @@ -82,46 +82,6 @@ export async function writeTypekitDocs(libraryPath: string, outputDir: string): } } -async function extractUsageDocFromLibrary(libraryPath: string): Promise { - // Look for typekit files in the library and extract @usageDoc - async function searchDirectory(dir: string): Promise { - try { - const entries = await readdir(dir, { withFileTypes: true }); - for (const entry of entries) { - const fullPath = joinPaths(dir, entry.name); - if (entry.isDirectory()) { - const result = await searchDirectory(fullPath); - if (result) return result; - } else if (entry.isFile() && entry.name.endsWith(".ts")) { - const content = await readFile(fullPath, "utf-8"); - const usageMatch = content.match( - /@usageDoc\s+([\s\S]*?)(?:\n\s*\*\s*@(?:experimental|typekit)|\n\s*\*\/)/, - ); - if (usageMatch) { - return usageMatch[1] - .split("\n") - .map((line) => line.replace(/^\s*\*\s?/, "")) - .join("\n") - .trim(); - } - } - } - } catch (error) { - // Ignore errors (e.g., directory doesn't exist) - } - return undefined; - } - - // Search in src/typekit and src/experimental/typekit directories - const typekitDir = joinPaths(libraryPath, "src", "typekit"); - let result = await searchDirectory(typekitDir); - if (!result) { - const experimentalTypekitDir = joinPaths(libraryPath, "src", "experimental", "typekit"); - result = await searchDirectory(experimentalTypekitDir); - } - return result; -} - async function getTypekitApi( libraryPath: string, pkgJson: PackageJson, @@ -132,9 +92,7 @@ async function getTypekitApi( } const namespaces: Record = {}; let hasExperimental = false; - - // Extract usage documentation from the library source files once - const collectionUsageDoc = await extractUsageDocFromLibrary(libraryPath); + let collectionUsageDoc: string | undefined; for (const pkgMember of api.packages[0].members) { for (const member of pkgMember.members) { @@ -150,7 +108,14 @@ async function getTypekitApi( hasExperimental = true; } - // Usage doc is extracted once for the entire collection from source files + // Extract usage documentation from @usageDoc custom block if present + const usageDocTag = docComment?.customBlocks.find( + (x) => x.blockTag.tagName === "@usageDoc", + ); + if (usageDocTag && !collectionUsageDoc) { + collectionUsageDoc = extractTextFromDocSection(usageDocTag.content); + } + const typekit: TypekitNamespace = resolveTypekit( member, [name], @@ -163,6 +128,35 @@ async function getTypekitApi( } } + function extractTextFromDocSection(section: DocSection): string { + // Extract text content preserving markdown structure + const textParts: string[] = []; + function visit(node: DocNode): void { + if (node.kind === "PlainText") { + textParts.push((node as any).text); + } else if (node.kind === "SoftBreak") { + textParts.push("\n"); + } else if (node.kind === "CodeSpan") { + textParts.push("`" + (node as any).code + "`"); + } else if (node.kind === "FencedCode") { + const fenced = node as any; + textParts.push("\n```" + (fenced.language || "") + "\n" + fenced.code + "\n```\n"); + } else if ((node as any).nodes) { + for (const child of (node as any).nodes) { + visit(child); + } + } + } + + // Access nested structure - TSDoc wraps content in paragraph nodes + if ((section as any).nodes) { + for (const node of (section as any).nodes) { + visit(node); + } + } + return textParts.join("").trim(); + } + function resolveTypekit( iface: ApiInterface, path: string[], From f454442989e7b6d88592b5210c7fe320019bbacf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 20:23:36 +0000 Subject: [PATCH 10/13] Address review comments: update changeset description and simplify example Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- ...copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md | 2 +- packages/http/src/experimental/typekit/kits/http-operation.ts | 2 -- .../src/content/docs/docs/libraries/http/reference/typekits.mdx | 2 -- 3 files changed, 1 insertion(+), 5 deletions(-) diff --git a/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md index ec8d422705d..39dba6dfa6f 100644 --- a/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md +++ b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md @@ -4,4 +4,4 @@ packages: - "@typespec/http" --- -Add @usageDoc JSDoc tag to HTTP typekit for auto-generated usage documentation \ No newline at end of file +Provide additional usage information and example usage of the experimental typekit \ No newline at end of file diff --git a/packages/http/src/experimental/typekit/kits/http-operation.ts b/packages/http/src/experimental/typekit/kits/http-operation.ts index b52d33d1ea7..c364ca1e4dd 100644 --- a/packages/http/src/experimental/typekit/kits/http-operation.ts +++ b/packages/http/src/experimental/typekit/kits/http-operation.ts @@ -31,11 +31,9 @@ import { * ### Example * * ```ts - * import { getHttpOperation } from "@typespec/http"; * import { $ } from "@typespec/compiler/typekit"; * import "@typespec/http/experimental/typekit"; * - * const [httpOperation] = getHttpOperation(program, operation); * const responses = $(program).httpOperation.flattenResponses(httpOperation); * ``` */ diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index aae47ba1aed..bab905a75ab 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -21,11 +21,9 @@ The first import registers the HTTP-specific typekit extensions. This import onl ### Example ```ts -import { getHttpOperation } from "@typespec/http"; import { $ } from "@typespec/compiler/typekit"; import "@typespec/http/experimental/typekit"; -const [httpOperation] = getHttpOperation(program, operation); const responses = $(program).httpOperation.flattenResponses(httpOperation); ``` From 499a3a779bae5378e85a1bea4a779b755ff41746 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 20:52:41 +0000 Subject: [PATCH 11/13] Simplify changeset description per review feedback Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- ...copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md index 39dba6dfa6f..57ac41306b4 100644 --- a/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md +++ b/.chronus/changes/copilot-fix-http-typekits-documentation-2026-2-3-22-21-43.md @@ -4,4 +4,4 @@ packages: - "@typespec/http" --- -Provide additional usage information and example usage of the experimental typekit \ No newline at end of file +Provide example usage of the experimental typekit in reference documentation \ No newline at end of file From 5b5706cf8099eabfe06e258cbff622ee2ff22f81 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 22:14:39 +0000 Subject: [PATCH 12/13] Auto-generate usage info from library metadata, remove @usageDoc mechanism Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../typekit/kits/http-operation.ts | 20 ------- packages/tspd/src/ref-doc/api-extractor.ts | 4 -- .../src/ref-doc/components/typekits-file.tsx | 29 ++++++++-- packages/tspd/src/ref-doc/typekit-docs.ts | 53 +------------------ .../libraries/http/reference/typekits.mdx | 14 +---- .../standard-library/reference/typekits.mdx | 9 ++++ 6 files changed, 37 insertions(+), 92 deletions(-) diff --git a/packages/http/src/experimental/typekit/kits/http-operation.ts b/packages/http/src/experimental/typekit/kits/http-operation.ts index c364ca1e4dd..4d9b837e68f 100644 --- a/packages/http/src/experimental/typekit/kits/http-operation.ts +++ b/packages/http/src/experimental/typekit/kits/http-operation.ts @@ -16,26 +16,6 @@ import { * Utilities for working with HTTP operations. * @typekit httpOperation * @experimental - * @usageDoc - * ## Usage - * - * To use these typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: - * - * ```ts - * import "@typespec/http/experimental/typekit"; - * import { $ } from "@typespec/compiler/typekit"; - * ``` - * - * The first import registers the HTTP-specific typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. - * - * ### Example - * - * ```ts - * import { $ } from "@typespec/compiler/typekit"; - * import "@typespec/http/experimental/typekit"; - * - * const responses = $(program).httpOperation.flattenResponses(httpOperation); - * ``` */ export interface HttpOperationKit { /** diff --git a/packages/tspd/src/ref-doc/api-extractor.ts b/packages/tspd/src/ref-doc/api-extractor.ts index 135cc336364..e73af12bfa5 100644 --- a/packages/tspd/src/ref-doc/api-extractor.ts +++ b/packages/tspd/src/ref-doc/api-extractor.ts @@ -75,10 +75,6 @@ export function createApiModelFileForExport( tagName: "@typekit", syntaxKind: "block", }, - { - tagName: "@usageDoc", - syntaxKind: "block", - }, ], }), packageJsonFullPath: joinPaths(libraryPath, "package.json"), diff --git a/packages/tspd/src/ref-doc/components/typekits-file.tsx b/packages/tspd/src/ref-doc/components/typekits-file.tsx index be84e664553..02bf69b08ce 100644 --- a/packages/tspd/src/ref-doc/components/typekits-file.tsx +++ b/packages/tspd/src/ref-doc/components/typekits-file.tsx @@ -12,7 +12,22 @@ import { format as prettierFormat } from "prettier"; import { TypekitCollection } from "../typekit-docs.js"; import { TypekitSection } from "./typekit-section.js"; -export function createTypekitDocs(typekit: TypekitCollection) { +export function createTypekitDocs(typekit: TypekitCollection, packageName: string) { + // Determine the import path based on package name and experimental status + const isHttpPackage = packageName === "@typespec/http"; + const isCompilerPackage = packageName === "@typespec/compiler"; + + // Generate import statement based on package + let importStatement: string; + if (isHttpPackage && typekit.isExperimental) { + importStatement = `import "@typespec/http/experimental/typekit";`; + } else if (isCompilerPackage) { + importStatement = `import "@typespec/compiler/typekit";`; + } else { + // Generic case for other packages + importStatement = `import "${packageName}/typekit";`; + } + const jsxContent = ( @@ -29,11 +44,15 @@ export function createTypekitDocs(typekit: TypekitCollection) { - `} - {typekit.usageDoc && - code` - ${typekit.usageDoc} + To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: + + \`\`\`ts + ${importStatement} + import { $ } from "@typespec/compiler/typekit"; + \`\`\` + + The first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. `} )} diff --git a/packages/tspd/src/ref-doc/typekit-docs.ts b/packages/tspd/src/ref-doc/typekit-docs.ts index 37d23ce1e85..b631c08091f 100644 --- a/packages/tspd/src/ref-doc/typekit-docs.ts +++ b/packages/tspd/src/ref-doc/typekit-docs.ts @@ -16,7 +16,6 @@ import { readPackageJson } from "./utils/misc.js"; export interface TypekitCollection { namespaces: Record; isExperimental?: boolean; - usageDoc?: string; } export interface TypekitNamespace { @@ -25,7 +24,6 @@ export interface TypekitNamespace { doc?: DocSection; entries: Record; isExperimental?: boolean; - usageDoc?: string; } type TypekitEntryDoc = TypekitNamespace | TypekitFunctionDoc; @@ -76,7 +74,7 @@ export async function writeTypekitDocs(libraryPath: string, outputDir: string): if (!typekits) { return; } - const output = await createTypekitDocs(typekits); + const output = await createTypekitDocs(typekits, pkgJson.name); for (const [file, content] of Object.entries(output)) { await writeFile(joinPaths(outputDir, file), content); } @@ -92,7 +90,6 @@ async function getTypekitApi( } const namespaces: Record = {}; let hasExperimental = false; - let collectionUsageDoc: string | undefined; for (const pkgMember of api.packages[0].members) { for (const member of pkgMember.members) { @@ -108,60 +105,17 @@ async function getTypekitApi( hasExperimental = true; } - // Extract usage documentation from @usageDoc custom block if present - const usageDocTag = docComment?.customBlocks.find( - (x) => x.blockTag.tagName === "@usageDoc", - ); - if (usageDocTag && !collectionUsageDoc) { - collectionUsageDoc = extractTextFromDocSection(usageDocTag.content); - } - - const typekit: TypekitNamespace = resolveTypekit( - member, - [name], - isExperimental, - collectionUsageDoc, - ); + const typekit: TypekitNamespace = resolveTypekit(member, [name], isExperimental); namespaces[name] = typekit; } } } } - function extractTextFromDocSection(section: DocSection): string { - // Extract text content preserving markdown structure - const textParts: string[] = []; - function visit(node: DocNode): void { - if (node.kind === "PlainText") { - textParts.push((node as any).text); - } else if (node.kind === "SoftBreak") { - textParts.push("\n"); - } else if (node.kind === "CodeSpan") { - textParts.push("`" + (node as any).code + "`"); - } else if (node.kind === "FencedCode") { - const fenced = node as any; - textParts.push("\n```" + (fenced.language || "") + "\n" + fenced.code + "\n```\n"); - } else if ((node as any).nodes) { - for (const child of (node as any).nodes) { - visit(child); - } - } - } - - // Access nested structure - TSDoc wraps content in paragraph nodes - if ((section as any).nodes) { - for (const node of (section as any).nodes) { - visit(node); - } - } - return textParts.join("").trim(); - } - function resolveTypekit( iface: ApiInterface, path: string[], isExperimental: boolean, - usageDoc?: string, ): TypekitNamespace { const typekit: TypekitNamespace = { name: path[0], @@ -169,7 +123,6 @@ async function getTypekitApi( doc: iface.tsdocComment?.summarySection, entries: {}, isExperimental, - usageDoc, }; for (const member of iface.members) { if (member instanceof ApiPropertySignature) { @@ -181,7 +134,6 @@ async function getTypekitApi( subkit.resolvedApiItem as ApiInterface, [...path, member.displayName], isExperimental, - undefined, // Sub-kits don't have their own usage docs ); } else if (propertyReference.toString() === "@typespec/compiler!Diagnosable:type") { typekit.entries[member.displayName] = { @@ -234,6 +186,5 @@ async function getTypekitApi( return { namespaces, isExperimental: hasExperimental, - usageDoc: collectionUsageDoc, }; } diff --git a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx index bab905a75ab..e3eb80f1765 100644 --- a/website/src/content/docs/docs/libraries/http/reference/typekits.mdx +++ b/website/src/content/docs/docs/libraries/http/reference/typekits.mdx @@ -7,25 +7,15 @@ import { Badge, Aside } from '@astrojs/starlight/components'; -## Usage -To use these typekits in your TypeSpec emitter or tool, you need to import the experimental typekit module: +To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: ```ts import "@typespec/http/experimental/typekit"; import { $ } from "@typespec/compiler/typekit"; ``` -The first import registers the HTTP-specific typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. - -### Example - -```ts -import { $ } from "@typespec/compiler/typekit"; -import "@typespec/http/experimental/typekit"; - -const responses = $(program).httpOperation.flattenResponses(httpOperation); -``` +The first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. ## model diff --git a/website/src/content/docs/docs/standard-library/reference/typekits.mdx b/website/src/content/docs/docs/standard-library/reference/typekits.mdx index d77f41a5fa6..f7b910b622d 100644 --- a/website/src/content/docs/docs/standard-library/reference/typekits.mdx +++ b/website/src/content/docs/docs/standard-library/reference/typekits.mdx @@ -8,6 +8,15 @@ import { Badge, Aside } from '@astrojs/starlight/components'; **Experimental Feature**: These typekits are currently experimental. The API surface is volatile and may have breaking changes without notice. Use with caution in production environments. +To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: + +```ts +import "@typespec/compiler/typekit"; +import { $ } from "@typespec/compiler/typekit"; +``` + +The first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. + ## array Typekits for working with array types(Model with number indexer). From 843912c88374c347beee9a47678595884e1ba94a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Mar 2026 00:49:01 +0000 Subject: [PATCH 13/13] Remove package-specific logic and skip usage instructions for compiler typekits Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- .../src/ref-doc/components/typekits-file.tsx | 30 ++++++++++--------- .../standard-library/reference/typekits.mdx | 9 ------ 2 files changed, 16 insertions(+), 23 deletions(-) diff --git a/packages/tspd/src/ref-doc/components/typekits-file.tsx b/packages/tspd/src/ref-doc/components/typekits-file.tsx index 02bf69b08ce..2bac8c92f3c 100644 --- a/packages/tspd/src/ref-doc/components/typekits-file.tsx +++ b/packages/tspd/src/ref-doc/components/typekits-file.tsx @@ -13,20 +13,12 @@ import { TypekitCollection } from "../typekit-docs.js"; import { TypekitSection } from "./typekit-section.js"; export function createTypekitDocs(typekit: TypekitCollection, packageName: string) { - // Determine the import path based on package name and experimental status - const isHttpPackage = packageName === "@typespec/http"; const isCompilerPackage = packageName === "@typespec/compiler"; - // Generate import statement based on package - let importStatement: string; - if (isHttpPackage && typekit.isExperimental) { - importStatement = `import "@typespec/http/experimental/typekit";`; - } else if (isCompilerPackage) { - importStatement = `import "@typespec/compiler/typekit";`; - } else { - // Generic case for other packages - importStatement = `import "${packageName}/typekit";`; - } + // Construct import path: for experimental typekits, use /experimental/typekit pattern + const typekitImportPath = typekit.isExperimental + ? `${packageName}/experimental/typekit` + : `${packageName}/typekit`; const jsxContent = ( @@ -37,7 +29,7 @@ export function createTypekitDocs(typekit: TypekitCollection, packageName: strin import { Badge${typekit.isExperimental ? ", Aside" : ""} } from '@astrojs/starlight/components'; `} - {typekit.isExperimental && ( + {typekit.isExperimental && !isCompilerPackage && ( <> {code` @@ -48,7 +40,7 @@ export function createTypekitDocs(typekit: TypekitCollection, packageName: strin To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: \`\`\`ts - ${importStatement} + import "${typekitImportPath}"; import { $ } from "@typespec/compiler/typekit"; \`\`\` @@ -56,6 +48,16 @@ export function createTypekitDocs(typekit: TypekitCollection, packageName: strin `} )} + {typekit.isExperimental && isCompilerPackage && ( + <> + {code` + + + `} + + )} {(x) => } diff --git a/website/src/content/docs/docs/standard-library/reference/typekits.mdx b/website/src/content/docs/docs/standard-library/reference/typekits.mdx index f7b910b622d..d77f41a5fa6 100644 --- a/website/src/content/docs/docs/standard-library/reference/typekits.mdx +++ b/website/src/content/docs/docs/standard-library/reference/typekits.mdx @@ -8,15 +8,6 @@ import { Badge, Aside } from '@astrojs/starlight/components'; **Experimental Feature**: These typekits are currently experimental. The API surface is volatile and may have breaking changes without notice. Use with caution in production environments. -To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: - -```ts -import "@typespec/compiler/typekit"; -import { $ } from "@typespec/compiler/typekit"; -``` - -The first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important. - ## array Typekits for working with array types(Model with number indexer).