From 2a9ca1d1e111cca089c6e7977bbb300bb8713112 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 13 Jan 2025 13:35:04 +0200 Subject: [PATCH] docs: fixes to workflow reference tooling (#10931) --- .../src/resources/helpers/comments.ts | 1 + .../src/resources/helpers/step-examples.ts | 15 ++----- .../resources/helpers/workflow-examples.ts | 40 +++++-------------- .../src/resources/helpers/workflow-hooks.ts | 13 ++++-- .../src/resources/helpers/workflow-input.ts | 1 + .../src/resources/helpers/workflow-output.ts | 1 + .../src/utils/beautify-code.ts | 13 ++++++ .../src/utils/reflection-formatter.ts | 13 ++++++ .../typedoc-plugin-workflows/src/plugin.ts | 23 ++++++++++- 9 files changed, 75 insertions(+), 45 deletions(-) create mode 100644 www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts index d2e064fb76965..7b63a6d3f4ad7 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts @@ -9,6 +9,7 @@ const EXCLUDED_TAGS = [ "@typeParamDefinition", "@version", "@tags", + "@summary", ] export default function () { diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts index e6ad34d10e984..095b3dc91418a 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-examples.ts @@ -1,9 +1,7 @@ import Handlebars from "handlebars" import { DeclarationReflection, SignatureReflection } from "typedoc" import { getReflectionTypeFakeValueStr, getStepInputType } from "utils" -import pkg from "js-beautify" - -const { js_beautify } = pkg +import beautifyCode from "../../utils/beautify-code.js" export default function () { Handlebars.registerHelper( @@ -39,8 +37,7 @@ function generateStepExample(stepReflection: DeclarationReflection): string { // generate example return ` \`\`\`ts title="src/workflows/my-workflow.ts" -${js_beautify( - `import { createWorkflow } from "@medusajs/framework/workflows-sdk" +${beautifyCode(`import { createWorkflow } from "@medusajs/framework/workflows-sdk" import { ${stepReflection.name} } from "@medusajs/medusa/core-flows" const myWorkflow = createWorkflow( @@ -48,13 +45,7 @@ const myWorkflow = createWorkflow( () => { const data = ${stepReflection.name}(${inputStr}) } -)`, - { - indent_size: 2, - brace_style: "preserve-inline", - wrap_line_length: 80, - } -)} +)`)} \`\`\` ` } diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts index c3d3f473052d4..53241b8a67fc3 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts @@ -1,9 +1,7 @@ import Handlebars from "handlebars" -import pkg from "js-beautify" import { DeclarationReflection, SignatureReflection } from "typedoc" import { getReflectionTypeFakeValueStr, getWorkflowInputType } from "utils" - -const { js_beautify } = pkg +import beautifyCode from "../../utils/beautify-code.js" export default function () { Handlebars.registerHelper( @@ -54,18 +52,12 @@ function getExecutionCodeTabs({ workflowName: string }): string { exampleCode = exampleCode.replace("```ts\n", "").replace("\n```", "") - const beautifyOptions: pkg.JSBeautifyOptions = { - indent_size: 2, - brace_style: "preserve-inline", - wrap_line_length: 80, - } return ` \`\`\`ts title="src/workflows/my-workflow.ts" -${js_beautify( - `import { createWorkflow } from "@medusajs/framework/workflows-sdk" +${beautifyCode(`import { createWorkflow } from "@medusajs/framework/workflows-sdk" import { ${workflowName} } from "@medusajs/medusa/core-flows" const myWorkflow = createWorkflow( @@ -74,19 +66,17 @@ const myWorkflow = createWorkflow( ${exampleCode .replace(`{ result }`, "result") .replace(`await `, "") - .replace(`(container)\n\t.run(`, ".runAsStep(")} + .replace(`(container)`, "") + .replace(".run(", ".runAsStep(")} } -)`, - beautifyOptions -)} +)`)} \`\`\` \`\`\`ts title="src/api/workflow/route.ts" -${js_beautify( - `import type { +${beautifyCode(`import type { MedusaRequest, MedusaResponse, } from "@medusajs/framework/http" @@ -100,17 +90,14 @@ export async function POST( res.send(result) } -`, - beautifyOptions -)} +`)} \`\`\` \`\`\`ts title="src/subscribers/order-placed.ts" -${js_beautify( - `import { +${beautifyCode(`import { type SubscriberConfig, type SubscriberArgs, } from "@medusajs/framework" @@ -127,17 +114,14 @@ export default async function handleOrderPlaced({ export const config: SubscriberConfig = { event: "order.placed", -}`, - beautifyOptions -)} +}`)} \`\`\` \`\`\`ts title="src/jobs/message-daily.ts" -${js_beautify( - `import { MedusaContainer } from "@medusajs/framework/types" +${beautifyCode(`import { MedusaContainer } from "@medusajs/framework/types" import { ${workflowName} } from "@medusajs/medusa/core-flows" export default async function myCustomJob( @@ -151,9 +135,7 @@ export default async function myCustomJob( export const config = { name: "run-once-a-day", schedule: "0 0 * * *", -}`, - beautifyOptions -)} +}`)} \`\`\` diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts index b6a3b3a6c9964..68e6323a691f4 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts @@ -2,6 +2,7 @@ import { MarkdownTheme } from "../../theme.js" import Handlebars from "handlebars" import { SignatureReflection } from "typedoc" import { cleanUpHookInput, getProjectChild } from "utils" +import beautifyCode from "../../utils/beautify-code.js" export default function (theme: MarkdownTheme) { Handlebars.registerHelper( @@ -19,7 +20,7 @@ export default function (theme: MarkdownTheme) { return "" } - let str = `${Handlebars.helpers.titleLevel()} Hooks` + let str = `${Handlebars.helpers.titleLevel()} Hooks\n\nHooks allow you to inject custom functionalities into the workflow. You'll receive data from the workflow, as well as additional data sent through an HTTP request.\n\nLearn more about [Hooks](https://docs.medusajs.com/learn/fundamentals/workflows/workflow-hooks) and [Additional Data](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data).\n\n` Handlebars.helpers.incrementCurrentTitleLevel() @@ -39,14 +40,20 @@ export default function (theme: MarkdownTheme) { str += `\n\n${hooksTitleLevel} ${hook.name}\n\n` + if (hookReflection.comment?.summary) { + str += `${Handlebars.helpers.comment( + hookReflection.comment.summary + )}\n\n` + } + const hookExample = hookReflection.comment?.getTag(`@example`) if (hookExample) { Handlebars.helpers.incrementCurrentTitleLevel() const innerTitleLevel = Handlebars.helpers.titleLevel() - str += `${innerTitleLevel} Example\n\n\`\`\`ts\n${Handlebars.helpers.comment( - hookExample.content + str += `${innerTitleLevel} Example\n\n\`\`\`ts\n${beautifyCode( + Handlebars.helpers.comment(hookExample.content) )}\n\`\`\`\n\n${innerTitleLevel} Input\n\n` Handlebars.helpers.decrementCurrentTitleLevel() diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts index 06bf2afa9aeaa..013ef8f8335a1 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts @@ -25,6 +25,7 @@ export default function (theme: MarkdownTheme) { project: this.project || options.data.theme.project, maxLevel, wrapObject: true, + isReturn: false, }) if (!input.length) { diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts index 27c288c00987f..82607c0af375a 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts @@ -25,6 +25,7 @@ export default function (theme: MarkdownTheme) { project: this.project || options.data.theme.project, maxLevel, wrapObject: true, + isReturn: false, }) if (!output.length) { diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts new file mode 100644 index 0000000000000..b689e7cad9bc6 --- /dev/null +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/beautify-code.ts @@ -0,0 +1,13 @@ +import pkg from "js-beautify" + +const { js_beautify } = pkg + +export default function beautifyCode(code: string): string { + const beautifyOptions: pkg.JSBeautifyOptions = { + indent_size: 2, + brace_style: "preserve-inline", + wrap_line_length: 80, + } + + return js_beautify(code, beautifyOptions) +} diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts index 43aa644557ec5..1e279bc4e251d 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts @@ -19,6 +19,7 @@ import { } from "utils" import { MarkdownTheme } from "../theme.js" import { getDmlProperties, isDmlEntity } from "utils" +import { loadComment } from "./reflection-type-parameters.js" const ALLOWED_KINDS: ReflectionKind[] = [ ReflectionKind.EnumMember, @@ -338,6 +339,18 @@ export function getComments( return parameter.type?.declaration?.signatures[0]?.comment } } + if (!parameter.comment && parameter.type?.type === "reference") { + // try to load comment + const commentContent = loadComment(parameter.type.name, parameter.project) + if (commentContent) { + return new Comment([ + { + kind: "text", + text: commentContent, + }, + ]) + } + } return parameter.comment } diff --git a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts index d421bc306d29b..1645793b9f521 100644 --- a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts +++ b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts @@ -207,6 +207,7 @@ class WorkflowsPlugin { workflow, workflowVarName: parentReflection.name, workflowReflection, + workflowComments: parentReflection.comment?.blockTags, }) if (!steps.length) { @@ -246,12 +247,14 @@ class WorkflowsPlugin { workflow, workflowVarName, workflowReflection, + workflowComments = [], }: { initializer: ts.CallExpression context: Context workflow?: WorkflowDefinition workflowVarName: string workflowReflection: SignatureReflection + workflowComments?: CommentTag[] }): ParsedStep[] { const steps: ParsedStep[] = [] const initializerName = this.helper.normalizeName( @@ -292,6 +295,7 @@ class WorkflowsPlugin { context, inputSymbol: initializer.arguments[1].symbol as ts.Symbol, workflowName: workflowVarName, + workflowComments, }) } else { const initializerReflection = findReflectionInNamespaces( @@ -478,11 +482,13 @@ class WorkflowsPlugin { context, inputSymbol, workflowName, + workflowComments, }: { stepId: string context: Context inputSymbol: ts.Symbol workflowName: string + workflowComments?: CommentTag[] }): DeclarationReflection { const declarationReflection = context.createDeclarationReflection( ReflectionKind.Function, @@ -492,7 +498,12 @@ class WorkflowsPlugin { ) declarationReflection.comment = new Comment() - declarationReflection.comment.summary = [ + + const hookComment = workflowComments?.find( + (tag) => tag.tag === `@property` && tag.name === `hooks.${stepId}` + ) + + declarationReflection.comment.summary = hookComment?.content || [ { kind: "text", text: "This step is a hook that you can inject custom functionality into.", @@ -515,6 +526,16 @@ class WorkflowsPlugin { if (parameter.type.name === "__object") { parameter.type.name = "object" parameter.type.qualifiedName = "object" + + if (!parameter.comment?.summary) { + parameter.comment = new Comment() + parameter.comment.summary = [ + { + kind: "text", + text: "The input data for the hook.", + }, + ] + } } signatureReflection.parameters = []