@typespec/tspd 0.70.0-dev.2 → 0.70.0

package/dist/src/ref-doc/emitters/starlight.js

@@ -1,213 +1,177 @@
-import { codeblock, inlinecode, renderMarkdowDoc, section, } from "../utils/markdown.js";
+import { codeblock, inlinecode, renderMarkdowDoc, section } from "../utils/markdown.js";
 import { MarkdownRenderer, groupByNamespace } from "./markdown.js";
+
 /**
  * Render doc to a markdown using docusaurus addons.
  */
 export function renderToAstroStarlightMarkdown(refDoc) {
-    const renderer = new StarlightRenderer(refDoc);
-    const files = {
-        "index.mdx": renderIndexFile(renderer, refDoc),
-    };
-    const decoratorFile = renderDecoratorFile(renderer, refDoc);
-    if (decoratorFile) {
-        files["decorators.md"] = decoratorFile;
-    }
-    const interfaceFile = renderInterfacesFile(renderer, refDoc);
-    if (interfaceFile) {
-        files["interfaces.md"] = interfaceFile;
+  const renderer = new StarlightRenderer(refDoc);
+  const files = {
+    "index.mdx": renderIndexFile(renderer, refDoc)
+  };
+  const decoratorFile = renderDecoratorFile(renderer, refDoc);
+  if (decoratorFile) {
+    files["decorators.md"] = decoratorFile;
+  }
+  const interfaceFile = renderInterfacesFile(renderer, refDoc);
+  if (interfaceFile) {
+    files["interfaces.md"] = interfaceFile;
+  }
+  const dataTypes = renderDataTypes(renderer, refDoc);
+  if (dataTypes) {
+    files["data-types.md"] = dataTypes;
+  }
+  const emitter = renderEmitter(renderer, refDoc);
+  if (emitter) {
+    files["emitter.md"] = emitter;
+  }
+  const linter = renderLinter(renderer, refDoc);
+  if (linter) {
+    files["linter.md"] = linter;
+  }
+  return files;
+}
+function renderIndexFile(renderer, refDoc) {
+  const content = ["---", `title: Overview`, `sidebar_position: 0`, "toc_min_heading_level: 2", "toc_max_heading_level: 3", "---", "import { Tabs, TabItem } from '@astrojs/starlight/components';", "", refDoc.description ?? [], renderer.install(refDoc), refDoc.emitter?.options ? section("Emitter usage", `[See documentation](./emitter.md)`) : [], groupByNamespace(refDoc.namespaces, namespace => {
+    const content = [];
+    if (namespace.decorators.length > 0) {
+      content.push(section("Decorators", renderer.toc(namespace.decorators)));
     }
-    const dataTypes = renderDataTypes(renderer, refDoc);
-    if (dataTypes) {
-        files["data-types.md"] = dataTypes;
+    if (namespace.interfaces.length > 0) {
+      content.push(section("Interfaces", renderer.toc(namespace.interfaces)));
     }
-    const emitter = renderEmitter(renderer, refDoc);
-    if (emitter) {
-        files["emitter.md"] = emitter;
+    if (namespace.operations.length > 0) {
+      content.push(section("Operations", renderer.toc(namespace.operations)));
     }
-    const linter = renderLinter(renderer, refDoc);
-    if (linter) {
-        files["linter.md"] = linter;
+    if (namespace.models.length > 0) {
+      content.push(section("Models", renderer.toc(namespace.models)));
     }
-    return files;
-}
-function renderIndexFile(renderer, refDoc) {
-    const content = [
-        "---",
-        `title: Overview`,
-        `sidebar_position: 0`,
-        "toc_min_heading_level: 2",
-        "toc_max_heading_level: 3",
-        "---",
-        "import { Tabs, TabItem } from '@astrojs/starlight/components';",
-        "",
-        refDoc.description ?? [],
-        renderer.install(refDoc),
-        refDoc.emitter?.options ? section("Emitter usage", `[See documentation](./emitter.md)`) : [],
-        groupByNamespace(refDoc.namespaces, (namespace) => {
-            const content = [];
-            if (namespace.decorators.length > 0) {
-                content.push(section("Decorators", renderer.toc(namespace.decorators)));
-            }
-            if (namespace.interfaces.length > 0) {
-                content.push(section("Interfaces", renderer.toc(namespace.interfaces)));
-            }
-            if (namespace.operations.length > 0) {
-                content.push(section("Operations", renderer.toc(namespace.operations)));
-            }
-            if (namespace.models.length > 0) {
-                content.push(section("Models", renderer.toc(namespace.models)));
-            }
-            return content;
-        }),
-    ];
-    return renderMarkdowDoc(content, 2);
+    return content;
+  })];
+  return renderMarkdowDoc(content, 2);
 }
 export function renderDecoratorFile(renderer, refDoc, options) {
-    if (!refDoc.namespaces.some((x) => x.decorators.length > 0)) {
-        return undefined;
-    }
-    const title = options?.title ?? "Decorators";
-    const content = [
-        "---",
-        `title: "${title}"`,
-        "toc_min_heading_level: 2",
-        "toc_max_heading_level: 3",
-        "---",
-    ];
-    content.push(renderer.decoratorsSection(refDoc));
-    return renderMarkdowDoc(content, 2);
+  if (!refDoc.namespaces.some(x => x.decorators.length > 0)) {
+    return undefined;
+  }
+  const title = options?.title ?? "Decorators";
+  const content = ["---", `title: "${title}"`, "toc_min_heading_level: 2", "toc_max_heading_level: 3", "---"];
+  content.push(renderer.decoratorsSection(refDoc));
+  return renderMarkdowDoc(content, 2);
 }
 function renderInterfacesFile(renderer, refDoc) {
-    if (!refDoc.namespaces.some((x) => x.operations.length > 0 || x.interfaces.length > 0)) {
-        return undefined;
-    }
-    const content = ["---", `title: "Interfaces and Operations"`, "---"];
-    content.push(groupByNamespace(refDoc.namespaces, (namespace) => {
-        if (namespace.operations.length === 0 && namespace.interfaces.length === 0) {
-            return undefined;
-        }
-        const content = [];
-        for (const iface of namespace.interfaces) {
-            content.push(renderer.interface(iface), "");
-        }
-        for (const operation of namespace.operations) {
-            content.push(renderer.operation(operation), "");
-        }
-        return content;
-    }));
-    return renderMarkdowDoc(content, 2);
+  if (!refDoc.namespaces.some(x => x.operations.length > 0 || x.interfaces.length > 0)) {
+    return undefined;
+  }
+  const content = ["---", `title: "Interfaces and Operations"`, "---"];
+  content.push(groupByNamespace(refDoc.namespaces, namespace => {
+    if (namespace.operations.length === 0 && namespace.interfaces.length === 0) {
+      return undefined;
+    }
+    const content = [];
+    for (const iface of namespace.interfaces) {
+      content.push(renderer.interface(iface), "");
+    }
+    for (const operation of namespace.operations) {
+      content.push(renderer.operation(operation), "");
+    }
+    return content;
+  }));
+  return renderMarkdowDoc(content, 2);
 }
 export function renderDataTypes(renderer, refDoc, options) {
-    if (!refDoc.namespaces.some((x) => x.models.length > 0)) {
-        return undefined;
-    }
-    const title = options?.title ?? "Data types";
-    const content = ["---", `title: "${title}"`, "---"];
-    content.push(groupByNamespace(refDoc.namespaces, (namespace) => {
-        const modelCount = namespace.models.length +
-            namespace.enums.length +
-            namespace.unions.length +
-            namespace.scalars.length;
-        if (modelCount === 0) {
-            return undefined;
-        }
-        const content = [];
-        for (const model of namespace.models) {
-            content.push(renderer.model(model), "");
-        }
-        for (const e of namespace.enums) {
-            content.push(renderer.enum(e), "");
-        }
-        for (const union of namespace.unions) {
-            content.push(renderer.union(union), "");
-        }
-        for (const scalar of namespace.scalars) {
-            content.push(renderer.scalar(scalar), "");
-        }
-        return content;
-    }));
-    return renderMarkdowDoc(content, 2);
+  if (!refDoc.namespaces.some(x => x.models.length > 0)) {
+    return undefined;
+  }
+  const title = options?.title ?? "Data types";
+  const content = ["---", `title: "${title}"`, "---"];
+  content.push(groupByNamespace(refDoc.namespaces, namespace => {
+    const modelCount = namespace.models.length + namespace.enums.length + namespace.unions.length + namespace.scalars.length;
+    if (modelCount === 0) {
+      return undefined;
+    }
+    const content = [];
+    for (const model of namespace.models) {
+      content.push(renderer.model(model), "");
+    }
+    for (const e of namespace.enums) {
+      content.push(renderer.enum(e), "");
+    }
+    for (const union of namespace.unions) {
+      content.push(renderer.union(union), "");
+    }
+    for (const scalar of namespace.scalars) {
+      content.push(renderer.scalar(scalar), "");
+    }
+    return content;
+  }));
+  return renderMarkdowDoc(content, 2);
 }
 function renderEmitter(renderer, refDoc) {
-    if (refDoc.emitter?.options === undefined) {
-        return undefined;
-    }
-    const content = [
-        "---",
-        `title: "Emitter usage"`,
-        "---",
-        renderer.emitterUsage(refDoc),
-    ];
-    return renderMarkdowDoc(content, 2);
+  if (refDoc.emitter?.options === undefined) {
+    return undefined;
+  }
+  const content = ["---", `title: "Emitter usage"`, "---", renderer.emitterUsage(refDoc)];
+  return renderMarkdowDoc(content, 2);
 }
 function renderLinter(renderer, refDoc) {
-    if (refDoc.linter === undefined) {
-        return undefined;
-    }
-    const content = [
-        "---",
-        `title: "Linter usage"`,
-        "---",
-        renderer.linterUsage(refDoc),
-    ];
-    return renderMarkdowDoc(content, 2);
+  if (refDoc.linter === undefined) {
+    return undefined;
+  }
+  const content = ["---", `title: "Linter usage"`, "---", renderer.linterUsage(refDoc)];
+  return renderMarkdowDoc(content, 2);
 }
 export class StarlightRenderer extends MarkdownRenderer {
-    headingTitle(item) {
-        // Set an explicit anchor id.
-        return `${inlinecode(item.name)} {#${item.id}}`;
-    }
-    anchorId(item) {
-        // Set an explicit anchor id.
-        return item.id;
-    }
-    install(refDoc) {
-        return section("Install", tabs([
-            {
-                label: "In a spec",
-                content: codeblock(`npm install ${refDoc.name}`, "bash"),
-            },
-            {
-                label: "In a library",
-                content: codeblock(`npm install --save-peer ${refDoc.name}`, "bash"),
-            },
-        ]));
-    }
-    filename(type) {
-        switch (type.kind) {
-            case "decorator":
-                return "./decorators.md";
-            case "operation":
-            case "interface":
-                return "./interfaces.md";
-            case "model":
-            case "enum":
-            case "union":
-                return "./data-types.md";
-            default:
-                return "";
-        }
-    }
-    linterRuleLink(url) {
-        const homepage = this.refDoc.packageJson.docusaurusWebsite;
-        if (homepage && url.includes(homepage)) {
-            const fromRoot = url.replace(homepage, "");
-            return `${fromRoot}.md`;
-        }
-        else {
-            return url;
-        }
-    }
-    deprecationNotice(notice) {
-        return [":::caution", `**Deprecated**: ${notice.message}`, ":::"];
-    }
+  headingTitle(item) {
+    // Set an explicit anchor id.
+    return `${inlinecode(item.name)} {#${item.id}}`;
+  }
+  anchorId(item) {
+    // Set an explicit anchor id.
+    return item.id;
+  }
+  install(refDoc) {
+    return section("Install", tabs([{
+      label: "In a spec",
+      content: codeblock(`npm install ${refDoc.name}`, "bash")
+    }, {
+      label: "In a library",
+      content: codeblock(`npm install --save-peer ${refDoc.name}`, "bash")
+    }]));
+  }
+  filename(type) {
+    switch (type.kind) {
+      case "decorator":
+        return "./decorators.md";
+      case "operation":
+      case "interface":
+        return "./interfaces.md";
+      case "model":
+      case "enum":
+      case "union":
+        return "./data-types.md";
+      default:
+        return "";
+    }
+  }
+  linterRuleLink(url) {
+    const homepage = this.refDoc.packageJson.docusaurusWebsite;
+    if (homepage && url.includes(homepage)) {
+      const fromRoot = url.replace(homepage, "");
+      return `${fromRoot}.md`;
+    } else {
+      return url;
+    }
+  }
+  deprecationNotice(notice) {
+    return [":::caution", `**Deprecated**: ${notice.message}`, ":::"];
+  }
 }
 function tabs(tabs) {
-    const result = ["<Tabs>"];
-    for (const tab of tabs) {
-        result.push(`<TabItem  label="${tab.label}" default>`, "", tab.content, "", "</TabItem>");
-    }
-    result.push("</Tabs>", "");
-    return result.join("\n");
-}
-//# sourceMappingURL=starlight.js.map
+  const result = ["<Tabs>"];
+  for (const tab of tabs) {
+    result.push(`<TabItem  label="${tab.label}" default>`, "", tab.content, "", "</TabItem>");
+  }
+  result.push("</Tabs>", "");
+  return result.join("\n");
+}

package/dist/src/ref-doc/experimental.js

@@ -1,4 +1,4 @@
-import { compile, createDiagnosticCollector, joinPaths, NodeHost, } from "@typespec/compiler";
+import { compile, createDiagnosticCollector, joinPaths, NodeHost } from "@typespec/compiler";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import prettier from "prettier";
 import { generateJsApiDocs } from "./api-docs.js";
@@ -9,54 +9,57 @@ import { extractLibraryRefDocs, extractRefDocs } from "./extractor.js";
  * @experimental this is for experimental and is for internal use only. Breaking change to this API can happen at anytime.
  */
 export async function generateLibraryDocs(libraryPath, outputDir, options = {}) {
-    const diagnostics = createDiagnosticCollector();
-    const pkgJson = await readPackageJson(libraryPath);
-    const refDoc = diagnostics.pipe(await extractLibraryRefDocs(libraryPath));
-    const files = renderToAstroStarlightMarkdown(refDoc);
-    await mkdir(outputDir, { recursive: true });
-    const config = await prettier.resolveConfig(libraryPath);
-    for (const [name, content] of Object.entries(files)) {
-        const formatted = await formatMarkdown(name, content, config);
-        await writeFile(joinPaths(outputDir, name), formatted);
-    }
-    const readme = await formatMarkdown(joinPaths(libraryPath, "README.md"), await renderReadme(refDoc, libraryPath), config ?? {});
-    await writeFile(joinPaths(libraryPath, "README.md"), readme);
-    if (pkgJson.main && !options.skipJSApi) {
-        await generateJsApiDocs(libraryPath, joinPaths(outputDir, "js-api"));
-    }
-    return diagnostics.diagnostics;
+  const diagnostics = createDiagnosticCollector();
+  const pkgJson = await readPackageJson(libraryPath);
+  const refDoc = diagnostics.pipe(await extractLibraryRefDocs(libraryPath));
+  const files = renderToAstroStarlightMarkdown(refDoc);
+  await mkdir(outputDir, {
+    recursive: true
+  });
+  const config = await prettier.resolveConfig(libraryPath);
+  for (const [name, content] of Object.entries(files)) {
+    const formatted = await formatMarkdown(name, content, config);
+    await writeFile(joinPaths(outputDir, name), formatted);
+  }
+  const readme = await formatMarkdown(joinPaths(libraryPath, "README.md"), await renderReadme(refDoc, libraryPath), config ?? {});
+  await writeFile(joinPaths(libraryPath, "README.md"), readme);
+  if (pkgJson.main && !options.skipJSApi) {
+    await generateJsApiDocs(libraryPath, joinPaths(outputDir, "js-api"));
+  }
+  return diagnostics.diagnostics;
 }
 export async function resolveLibraryRefDocsBase(libraryPath, options = {}) {
-    const diagnostics = createDiagnosticCollector();
-    const pkgJson = await readPackageJson(libraryPath);
-    if (pkgJson.tspMain) {
-        const main = joinPaths(libraryPath, pkgJson.tspMain);
-        const program = await compile(NodeHost, main, {
-            parseOptions: { comments: true, docs: true },
-        });
-        const refDoc = diagnostics.pipe(extractRefDocs(program, options));
-        for (const diag of program.diagnostics ?? []) {
-            diagnostics.add(diag);
-        }
-        return diagnostics.wrap(refDoc);
+  const diagnostics = createDiagnosticCollector();
+  const pkgJson = await readPackageJson(libraryPath);
+  if (pkgJson.tspMain) {
+    const main = joinPaths(libraryPath, pkgJson.tspMain);
+    const program = await compile(NodeHost, main, {
+      parseOptions: {
+        comments: true,
+        docs: true
+      }
+    });
+    const refDoc = diagnostics.pipe(extractRefDocs(program, options));
+    for (const diag of program.diagnostics ?? []) {
+      diagnostics.add(diag);
     }
-    return undefined;
+    return diagnostics.wrap(refDoc);
+  }
+  return undefined;
 }
 async function readPackageJson(libraryPath) {
-    const buffer = await readFile(joinPaths(libraryPath, "package.json"));
-    return JSON.parse(buffer.toString());
+  const buffer = await readFile(joinPaths(libraryPath, "package.json"));
+  return JSON.parse(buffer.toString());
 }
 async function formatMarkdown(filename, content, options) {
-    try {
-        return await prettier.format(content, {
-            ...(options ?? {}),
-            parser: "markdown",
-        });
-    }
-    catch (e) {
-        // eslint-disable-next-line no-console
-        console.error(`Cannot format with prettier ${filename}`, e);
-        return content;
-    }
-}
-//# sourceMappingURL=experimental.js.map
+  try {
+    return await prettier.format(content, {
+      ...(options ?? {}),
+      parser: "markdown"
+    });
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.error(`Cannot format with prettier ${filename}`, e);
+    return content;
+  }
+}