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/.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..57ac41306b4 --- /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" +--- + +Provide example usage of the experimental typekit in reference documentation \ 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 c63e8a81e1d..2bac8c92f3c 100644 --- a/packages/tspd/src/ref-doc/components/typekits-file.tsx +++ b/packages/tspd/src/ref-doc/components/typekits-file.tsx @@ -12,16 +12,52 @@ 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 isCompilerPackage = packageName === "@typespec/compiler"; + + // Construct import path: for experimental typekits, use /experimental/typekit pattern + const typekitImportPath = typekit.isExperimental + ? `${packageName}/experimental/typekit` + : `${packageName}/typekit`; + const jsxContent = ( <> {code` - import { Badge } from '@astrojs/starlight/components'; + import { Badge${typekit.isExperimental ? ", Aside" : ""} } from '@astrojs/starlight/components'; `} + {typekit.isExperimental && !isCompilerPackage && ( + <> + {code` + + + + To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module: + + \`\`\`ts + import "${typekitImportPath}"; + 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. + `} + + )} + {typekit.isExperimental && isCompilerPackage && ( + <> + {code` + + + `} + + )} {(x) => } diff --git a/packages/tspd/src/ref-doc/typekit-docs.ts b/packages/tspd/src/ref-doc/typekit-docs.ts index 83e63569334..b631c08091f 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,8 @@ 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 +100,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 +133,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 +185,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 dbb44a734a6..e3eb80f1765 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,20 @@ title: "[API] Typekits" --- -import { Badge } from '@astrojs/starlight/components'; +import { Badge, Aside } from '@astrojs/starlight/components'; + + + +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 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 93bab0a07f6..d77f41a5fa6 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,11 @@ title: "[API] Typekits" --- -import { Badge } from '@astrojs/starlight/components'; +import { Badge, Aside } from '@astrojs/starlight/components'; + + ## array