@typespec/tspd 0.47.0-dev.0

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

@@ -0,0 +1,229 @@
+import { resolvePath } from "@typespec/compiler";
+import { readFile } from "fs/promises";
+import { stringify } from "yaml";
+import { codeblock, inlinecode, link, renderMarkdowDoc, section, table, } from "../utils/markdown.js";
+import { getTypeSignature } from "../utils/type-signature.js";
+async function loadTemplate(projectRoot, name) {
+    try {
+        const content = await readFile(resolvePath(projectRoot, `.tspd/docs/${name}.md`));
+        return content.toString();
+    }
+    catch (e) {
+        if (typeof e === "object" && (e === null || e === void 0 ? void 0 : e.code) === "ENOENT") {
+            return undefined;
+        }
+        throw e;
+    }
+}
+export async function renderReadme(refDoc, projectRoot) {
+    var _a;
+    const content = [];
+    const renderer = new MarkdownRenderer();
+    if (refDoc.description) {
+        content.push(refDoc.description);
+    }
+    content.push(renderer.install(refDoc));
+    const usageTemplate = await loadTemplate(projectRoot, "usage");
+    if (usageTemplate) {
+        content.push(section("Usage", [usageTemplate]));
+    }
+    if ((_a = refDoc.emitter) === null || _a === void 0 ? void 0 : _a.options) {
+        content.push(renderer.emitterUsage(refDoc));
+    }
+    if (refDoc.linter) {
+        content.push(renderer.linterUsage(refDoc));
+    }
+    if (refDoc.namespaces.some((x) => x.decorators.length > 0)) {
+        content.push(section("Decorators", renderer.decoratorsSection(refDoc, { includeToc: true })));
+    }
+    return renderMarkdowDoc(section(refDoc.name, content));
+}
+export function groupByNamespace(namespaces, callback) {
+    const content = [];
+    for (const namespace of namespaces) {
+        const contentForNamespace = callback(namespace);
+        if (contentForNamespace) {
+            content.push(section(namespace.id, contentForNamespace));
+        }
+    }
+    return content;
+}
+/**
+ * Github flavored markdown renderer.
+ */
+export class MarkdownRenderer {
+    headingTitle(item) {
+        return inlinecode(item.name);
+    }
+    anchorId(item) {
+        return `${item.name.toLowerCase().replace(/ /g, "-")}`;
+    }
+    //#region TypeSpec types
+    operation(op) {
+        const content = ["", op.doc, codeblock(op.signature, "typespec"), ""];
+        if (op.templateParameters) {
+            content.push(this.templateParameters(op.templateParameters));
+        }
+        content.push(this.examples(op.examples));
+        return section(this.headingTitle(op), content);
+    }
+    interface(iface) {
+        const content = ["", iface.doc, codeblock(iface.signature, "typespec"), ""];
+        if (iface.templateParameters) {
+            content.push(this.templateParameters(iface.templateParameters));
+        }
+        if (iface.interfaceOperations.length > 0) {
+            for (const op of iface.interfaceOperations) {
+                content.push(this.operation(op));
+            }
+        }
+        content.push(this.examples(iface.examples));
+        return section(this.headingTitle(iface), content);
+    }
+    model(model) {
+        const content = ["", model.doc, codeblock(model.signature, "typespec"), ""];
+        if (model.templateParameters) {
+            content.push(this.templateParameters(model.templateParameters));
+        }
+        content.push(this.examples(model.examples));
+        return section(this.headingTitle(model), content);
+    }
+    enum(e) {
+        const content = [
+            "",
+            e.doc,
+            codeblock(e.signature, "typespec"),
+            "",
+            this.examples(e.examples),
+        ];
+        return section(this.headingTitle(e), content);
+    }
+    union(union) {
+        const content = ["", union.doc, codeblock(union.signature, "typespec"), ""];
+        if (union.templateParameters) {
+            content.push(this.templateParameters(union.templateParameters));
+        }
+        content.push(this.examples(union.examples));
+        return section(this.headingTitle(union), content);
+    }
+    scalar(scalar) {
+        const content = ["", scalar.doc, codeblock(scalar.signature, "typespec"), ""];
+        if (scalar.templateParameters) {
+            content.push(this.templateParameters(scalar.templateParameters));
+        }
+        content.push(this.examples(scalar.examples));
+        return section(this.headingTitle(scalar), content);
+    }
+    templateParameters(templateParameters) {
+        const paramTable = [["Name", "Description"]];
+        for (const param of templateParameters) {
+            paramTable.push([param.name, param.doc]);
+        }
+        return section("Template Parameters", [table(paramTable), ""]);
+    }
+    decorator(dec) {
+        const content = ["", dec.doc, codeblock(dec.signature, "typespec"), ""];
+        content.push(section("Target", [dec.target.doc, inlinecode(getTypeSignature(dec.target.type.type)), ""]));
+        if (dec.parameters.length > 0) {
+            const paramTable = [["Name", "Type", "Description"]];
+            for (const param of dec.parameters) {
+                paramTable.push([param.name, inlinecode(getTypeSignature(param.type.type)), param.doc]);
+            }
+            content.push(section("Parameters", [table(paramTable), ""]));
+        }
+        else {
+            content.push(section("Parameters", ["None", ""]));
+        }
+        content.push(this.examples(dec.examples));
+        return section(this.headingTitle(dec), content);
+    }
+    examples(examples) {
+        const content = [];
+        if (examples.length === 0) {
+            return "";
+        }
+        for (const example of examples) {
+            const exampleContent = ["", example.content, ""];
+            if (example.title) {
+                content.push(section(example.title, exampleContent));
+            }
+            else {
+                content.push(exampleContent);
+            }
+        }
+        return section("Examples", content);
+    }
+    // #endregion TypeSpec types
+    /** Render all decorators */
+    decoratorsSection(refDoc, options = {}) {
+        return groupByNamespace(refDoc.namespaces, (namespace) => {
+            if (namespace.decorators.length === 0) {
+                return undefined;
+            }
+            return [
+                options.includeToc ? this.toc(namespace.decorators) : [],
+                namespace.decorators.map((x) => [this.decorator(x), ""]),
+            ];
+        });
+    }
+    toc(items, filename) {
+        return items.map((item) => ` - [${inlinecode(item.name)}](${filename !== null && filename !== void 0 ? filename : ""}#${this.anchorId(item)})`);
+    }
+    install(refDoc) {
+        return section("Install", [codeblock(`npm install ${refDoc.name}`, "bash")]);
+    }
+    emitterUsage(refDoc) {
+        var _a;
+        if (((_a = refDoc.emitter) === null || _a === void 0 ? void 0 : _a.options) === undefined) {
+            return [];
+        }
+        return section("Emitter", [
+            section("Usage", [
+                "1. Via the command line",
+                codeblock(`tsp compile . --emit=${refDoc.name}`, "bash"),
+                "2. Via the config",
+                codeblock(`emit:\n  - "${refDoc.name}" `, "yaml"),
+            ]),
+            this.emitterOptions(refDoc.emitter.options),
+        ]);
+    }
+    emitterOptions(options) {
+        const content = [];
+        for (const option of options) {
+            content.push(section(`${inlinecode(option.name)}`, [`**Type:** ${inlinecode(option.type)}`, ""]));
+            content.push(option.doc);
+        }
+        return section("Emitter options", content);
+    }
+    linterUsage(refDoc) {
+        if (refDoc.linter === undefined) {
+            return [];
+        }
+        const setupExample = stringify({
+            linter: refDoc.linter.ruleSets
+                ? { extends: [refDoc.linter.ruleSets[0].name] }
+                : { rules: {} },
+        });
+        return section("Linter", [
+            section("Usage", ["Add the following in `tspconfig.yaml`:", codeblock(setupExample, "yaml")]),
+            refDoc.linter.ruleSets
+                ? section("RuleSets", ["Available ruleSets:", this.toc(refDoc.linter.ruleSets)])
+                : [],
+            section("Rules", this.linterRuleToc(refDoc.linter.rules)),
+        ]);
+    }
+    linterRuleToc(rules) {
+        return table([
+            ["Name", "Description"],
+            ...rules.map((rule) => {
+                const name = inlinecode(rule.name);
+                const nameCell = rule.rule.url ? link(name, this.linterRuleLink(rule.rule.url)) : name;
+                return [nameCell, rule.rule.description];
+            }),
+        ]);
+    }
+    linterRuleLink(url) {
+        return url;
+    }
+}
+//# sourceMappingURL=markdown.js.map

package/dist/src/ref-doc/emitters/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../../../src/ref-doc/emitters/markdown.ts"],"names":[],"mappings":"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"}

package/dist/src/ref-doc/experimental.d.ts

@@ -0,0 +1,9 @@
+import { Diagnostic } from "@typespec/compiler";
+import { ExtractRefDocOptions } from "./extractor.js";
+import { TypeSpecRefDocBase } from "./types.js";
+/**
+ * @experimental this is for experimental and is for internal use only. Breaking change to this API can happen at anytime.
+ */
+export declare function generateLibraryDocs(libraryPath: string, outputDir: string, skipJSApi?: boolean): Promise<readonly Diagnostic[]>;
+export declare function resolveLibraryRefDocsBase(libraryPath: string, options?: ExtractRefDocOptions): Promise<[TypeSpecRefDocBase, readonly Diagnostic[]] | undefined>;
+//# sourceMappingURL=experimental.d.ts.map

package/dist/src/ref-doc/experimental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experimental.d.ts","sourceRoot":"","sources":["../../../src/ref-doc/experimental.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EAIX,MAAM,oBAAoB,CAAC;AAM5B,OAAO,EAAyB,oBAAoB,EAAkB,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,OAAe,GACzB,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAqBhC;AAED,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,kBAAkB,EAAE,SAAS,UAAU,EAAE,CAAC,GAAG,SAAS,CAAC,CAelE"}

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

@@ -0,0 +1,63 @@
+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";
+import { renderToDocusaurusMarkdown } from "./emitters/docusaurus.js";
+import { renderReadme } from "./emitters/markdown.js";
+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, skipJSApi = false) {
+    const diagnostics = createDiagnosticCollector();
+    const pkgJson = await readPackageJson(libraryPath);
+    const refDoc = diagnostics.pipe(await extractLibraryRefDocs(libraryPath));
+    const files = renderToDocusaurusMarkdown(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 !== null && config !== void 0 ? config : {});
+    await writeFile(joinPaths(libraryPath, "README.md"), readme);
+    if (pkgJson.main && !skipJSApi) {
+        await generateJsApiDocs(libraryPath, joinPaths(outputDir, "js-api"));
+    }
+    return diagnostics.diagnostics;
+}
+export async function resolveLibraryRefDocsBase(libraryPath, options = {}) {
+    var _a;
+    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 (_a = program.diagnostics) !== null && _a !== void 0 ? _a : []) {
+            diagnostics.add(diag);
+        }
+        return diagnostics.wrap(refDoc);
+    }
+    return undefined;
+}
+async function readPackageJson(libraryPath) {
+    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 !== null && options !== void 0 ? 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"experimental.js","sourceRoot":"","sources":["../../../src/ref-doc/experimental.ts"],"names":[],"mappings":"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"}

package/dist/src/ref-doc/extractor.d.ts

@@ -0,0 +1,11 @@
+import { Diagnostic, Program } from "@typespec/compiler";
+import { TypeSpecLibraryRefDoc, TypeSpecRefDocBase } from "./types.js";
+export declare function extractLibraryRefDocs(libraryPath: string): Promise<[TypeSpecLibraryRefDoc, readonly Diagnostic[]]>;
+export interface ExtractRefDocOptions {
+    namespaces?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+export declare function extractRefDocs(program: Program, options?: ExtractRefDocOptions): [TypeSpecRefDocBase, readonly Diagnostic[]];
+//# sourceMappingURL=extractor.d.ts.map

package/dist/src/ref-doc/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../src/ref-doc/extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,UAAU,EAwBV,OAAO,EAQR,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAcL,qBAAqB,EACrB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAGpB,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,qBAAqB,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAoCzD;AAOD,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAkCD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,oBAAyB,GACjC,CAAC,kBAAkB,EAAE,SAAS,UAAU,EAAE,CAAC,CAwF7C"}