docs: DX improvements to a workflow / step reference page (#10906)

www/utils/packages/typedoc-generate-references/src/constants/base-options.ts

@@ -14,7 +14,6 @@ export const baseOptions: Partial<TypeDocOptions> = {
   excludeInternal: true,
   excludeExternals: true,
   excludeReferences: true,
-  disableSources: true,
   sort: ["source-order"],
   validation: {
     notExported: false,

www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -77,6 +77,7 @@ import workflowHooksHelper from "./resources/helpers/workflow-hooks.js"
 import ifMemberShowTitleHelper from "./resources/helpers/if-member-show-title.js"
 import signatureCommentHelper from "./resources/helpers/signature-comment.js"
 import versionHelper from "./resources/helpers/version.js"
+import sourceCodeLinkHelper from "./resources/helpers/source-code-link.js"
 import { MarkdownTheme } from "./theme.js"
 import { getDirname } from "utils"
 
@@ -185,4 +186,5 @@ export function registerHelpers(theme: MarkdownTheme) {
   ifMemberShowTitleHelper(theme)
   signatureCommentHelper()
   versionHelper()
+  sourceCodeLinkHelper()
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/parameter-component.ts

@@ -10,7 +10,8 @@ export default function (theme: MarkdownTheme) {
     "parameterComponent",
     function (
       this: ReflectionParameterType[],
-      options: Handlebars.HelperOptions
+      options: Handlebars.HelperOptions,
+      extraProps?: Record<string, unknown>
     ) {
       const { parameterComponent, maxLevel, parameterComponentExtraProps } =
         theme.getFormattingOptionsForLocation()
@@ -34,7 +35,10 @@ export default function (theme: MarkdownTheme) {
       return formatParameterComponent({
         parameterComponent,
         componentItems: parameters,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          ...extraProps,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
     }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/source-code-link.ts

@@ -0,0 +1,17 @@
+import Handlebars from "handlebars"
+import { SignatureReflection } from "typedoc"
+
+export default function () {
+  Handlebars.registerHelper(
+    "sourceCodeLink",
+    function (this: SignatureReflection): string {
+      const source = this.parent.sources?.[0]
+
+      if (!source?.url) {
+        return ""
+      }
+
+      return `<SourceCodeLink link="${source.url}" />`
+    }
+  )
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-input.ts

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: input,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-output.ts

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: output,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts

@@ -60,6 +60,9 @@ export default function (theme: MarkdownTheme) {
             hash: {
               sectionTitle: hook.name,
             },
+          },
+          {
+            openedLevel: 1,
           }
         )
       })

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-input.ts

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: input,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-output.ts

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: output,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.workflow.hbs

@@ -8,6 +8,8 @@
 
 {{/if}}
 
+{{{sourceCodeLink}}}
+
 {{#if (sectionEnabled "member_signature_example")}}
 
 {{{example this}}}

www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/format-parameter-component.ts

@@ -48,9 +48,11 @@ export function formatParameterComponent({
 }: FormatParameterComponentProps): string {
   let extraPropsArr: string[] = []
   if (extraProps) {
-    extraPropsArr = Object.entries(extraProps).map(
-      ([key, value]) => `${key}=${JSON.stringify(value)}`
-    )
+    extraPropsArr = Object.entries(extraProps).map(([key, value]) => {
+      const valueJSON = JSON.stringify(value)
+      const valueStr = typeof value !== "string" ? `{${valueJSON}}` : valueJSON
+      return `${key}=${valueStr}`
+    })
   }
   // reorder component items to show required items first
   componentItems = sortComponentItems(componentItems)