Auto-generate experimental warnings and usage docs for typekits from library metadata

.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

.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

packages/tspd/src/ref-doc/components/typekits-file.tsx

@@ -12,16 +12,55 @@ 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`;
+
+  // Build import statements for code blocks - compiler package shows only typekit import,
+  // non-compiler experimental packages show both registration and typekit imports
+  const importStatements = isCompilerPackage
+    ? `import { $ } from "@typespec/compiler/typekit";`
+    : typekit.isExperimental
+      ? `import "${typekitImportPath}";\nimport { $ } from "@typespec/compiler/typekit";`
+      : `import { $ } from "@typespec/compiler/typekit";`;
+
+  // Build explanation text for experimental non-compiler packages
+  const sideEffectsExplanation =
+    typekit.isExperimental && !isCompilerPackage
+      ? "\n\nThe first import registers the typekit extensions. This import only needs to exist once in your compilation as only its side effects are important."
+      : "";
+
   const jsxContent = (
     <Output>
       <md.SourceFile path={`typekits.mdx`}>
         <>
           <md.Frontmatter jsValue={{ title: "[API] Typekits" }} />
           {code`
-        import { Badge } from '@astrojs/starlight/components';
+        import { Badge${typekit.isExperimental ? ", Aside" : ""} } from '@astrojs/starlight/components';
         `}
         </>
+        {typekit.isExperimental && (
+          <>
+            {code`
+
+        <Aside type="caution">
+        **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.
+        </Aside>
+        `}
+          </>
+        )}
+        {code`
+
+        To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module:
+
+        \`\`\`ts
+        ${importStatements}
+        \`\`\`${sideEffectsExplanation}
+        `}
         <md.Section>
           <For each={Object.values(typekit.namespaces)}>
             {(x) => <TypekitSection typekit={x} />}

packages/tspd/src/ref-doc/typekit-docs.ts

@@ -15,13 +15,15 @@ import { readPackageJson } from "./utils/misc.js";
 
 export interface TypekitCollection {
   namespaces: Record<string, TypekitNamespace>;
+  isExperimental?: boolean;
 }
 
 export interface TypekitNamespace {
   name: string;
   typeName: string;
   doc?: DocSection;
   entries: Record<string, TypekitEntryDoc>;
+  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<string, TypekitNamespace> = {};
+  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,
   };
 }

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';
+
+<Aside type="caution">
+**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.
+</Aside>
+
+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
 

website/src/content/docs/docs/standard-library/reference/typekits.mdx

@@ -2,7 +2,17 @@
 title: "[API] Typekits"
 ---
 
-import { Badge } from '@astrojs/starlight/components';
+import { Badge, Aside } from '@astrojs/starlight/components';
+
+<Aside type="caution">
+**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.
+</Aside>
+
+To use these typekits in your TypeSpec emitter or tool, you need to import the typekit module:
+
+```ts
+import { $ } from "@typespec/compiler/typekit";
+```
 
 ## array