docs: refactor medusa workflows reference (#8692)

* docs: fix handling of namespaces in core flows under definitions directory

* change nested handling

* docs-util: expand workflows under definitions in workflows reference

* remove check for definitions

www/packages/build-scripts/src/generate-edited-dates.ts

@@ -39,10 +39,15 @@ const getGitEditDatesOfPaths = async (
 // date doesn't accurately represent the publish date of the file.
 const getOsLastEditDates = async (
   paths: string[]
-): Promise<Record<string, string>> => {
+): Promise<Record<string, string | undefined>> => {
-  const editDates: Record<string, string> = {}
+  const editDates: Record<string, string | undefined> = {}
   await Promise.all(
     paths.map(async (filePath) => {
+      if (!existsSync(filePath)) {
+        // indicates that file was deleted
+        editDates[filePath] = undefined
+        return
+      }
       const fileStat = await stat(filePath)
 
       editDates[filePath] = fileStat.mtime.toISOString()
@@ -117,7 +122,7 @@ export const generateEditedDates = async () => {
   const type = generatedFileExists ? "git" : "all"
 
   let files: string[] = []
-  let editDates: Record<string, string> = {}
+  let editDates: Record<string, string | undefined> = {}
 
   if (type === "all") {
     // get all files in a project
@@ -144,6 +149,11 @@ export const generateEditedDates = async () => {
     )
 
     editDates = Object.assign(existingEditDates, editDates)
+
+    // delete items that don't exist anymore (their value is undefined)
+    Object.keys(editDates)
+      .filter((key) => editDates[key] === undefined)
+      .forEach((key) => delete editDates[key])
   }
 
   await writeFile(

www/packages/build-scripts/src/utils/get-core-flows-ref-sidebar-children.ts

@@ -37,46 +37,55 @@ export default async function getCoreFlowsRefSidebarChildren(): Promise<
       continue
     }
 
-    const namespaceBasePath = path.join(basePath, directory.name, "functions")
-
-    if (!existsSync(namespaceBasePath)) {
-      continue
-    }
-
-    const childDirs = readdirSync(namespaceBasePath, {
-      withFileTypes: true,
-    })
-
     const workflowItems: ItemsToAdd[] = []
     const stepItems: ItemsToAdd[] = []
 
-    for (const childDir of childDirs) {
+    const readItemsFromChildDirs = async (type: "Steps" | "Workflows") => {
-      if (!childDir.isDirectory()) {
+      const childNamespaceBasePath = path.join(
-        continue
+        basePath,
+        directory.name,
+        `${type}_${directory.name}`,
+        "functions"
+      )
+
+      if (!existsSync(childNamespaceBasePath)) {
+        return
       }
-
+      const childDirs = readdirSync(childNamespaceBasePath, {
-      const childDirPath = path.join(namespaceBasePath, childDir.name)
+        withFileTypes: true,
-      const childFile = readdirSync(childDirPath)
-
-      if (!childFile.length) {
-        continue
-      }
-
-      const sidebarItem = await getSidebarItemLink({
-        filePath: path.join(childDirPath, childFile[0]),
-        basePath: projPath,
-        fileBasename: childFile[0],
       })
 
-      if (sidebarItem) {
+      for (const childDir of childDirs) {
-        if (childDir.name.endsWith("Workflow")) {
+        if (!childDir.isDirectory()) {
-          workflowItems.push(sidebarItem)
+          continue
-        } else {
+        }
-          stepItems.push(sidebarItem)
+
+        const childDirPath = path.join(childNamespaceBasePath, childDir.name)
+        const childFile = readdirSync(childDirPath)
+
+        if (!childFile.length) {
+          continue
+        }
+
+        const sidebarItem = await getSidebarItemLink({
+          filePath: path.join(childDirPath, childFile[0]),
+          basePath: projPath,
+          fileBasename: childFile[0],
+        })
+
+        if (sidebarItem) {
+          if (childDir.name.endsWith("Workflow")) {
+            workflowItems.push(sidebarItem)
+          } else {
+            stepItems.push(sidebarItem)
+          }
         }
       }
     }
 
+    await readItemsFromChildDirs("Steps")
+    await readItemsFromChildDirs("Workflows")
+
     if (workflowItems.length || stepItems.length) {
       const item: ItemsToAdd = {
         type: "category",

www/packages/docs-ui/src/components/Card/Layout/Default/index.tsx

@@ -49,7 +49,7 @@ export const CardDefaultLayout = ({
           icon={image}
         />
       )}
-      <div className={clsx("flex flex-col flex-1", contentClassName)}>
+      <div className={clsx("flex flex-col flex-1 truncate", contentClassName)}>
         {title && (
           <div className="text-compact-small-plus text-medusa-fg-base truncate">
             {title}

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/core-flows.ts

@@ -11,7 +11,37 @@ const coreFlowsOptions: FormattingOptionsType = {
     workflowDiagramComponent: "WorkflowDiagram",
     mdxImports: [`import { TypeList, WorkflowDiagram } from "docs-ui"`],
   },
-  "^core_flows/.*/functions/.*Workflow/page\\.mdx": {
+  "^core_flows/.*/.*Steps_.*/page\\.mdx": {
+    reflectionGroups: {
+      Namespaces: false,
+      Enumerations: false,
+      Classes: false,
+      Interfaces: false,
+      "Type Aliases": false,
+      Variables: false,
+      "Enumeration Members": false,
+      Properties: false,
+      "Type Literals": false,
+      Functions: true,
+    },
+    hideTocHeaders: true,
+  },
+  "^core_flows/.*/.*Workflows_.*/page\\.mdx": {
+    reflectionGroups: {
+      Namespaces: false,
+      Enumerations: false,
+      Classes: false,
+      Interfaces: false,
+      "Type Aliases": false,
+      Variables: false,
+      "Enumeration Members": false,
+      Properties: false,
+      "Type Literals": false,
+      Functions: true,
+    },
+    hideTocHeaders: true,
+  },
+  "^core_flows/.*/Workflows_.*/functions/.*/page\\.mdx": {
     reflectionDescription:
       "This documentation provides a reference to the `{{alias}}`. It belongs to the `@medusajs/core-flows` package.",
     frontmatterData: {
@@ -24,7 +54,7 @@ const coreFlowsOptions: FormattingOptionsType = {
       suffix: "- Medusa Workflows API Reference",
     },
   },
-  "^core_flows/.*/functions/.*Step/page\\.mdx": {
+  "^core_flows/.*/Steps_.*/functions/.*/page\\.mdx": {
     reflectionDescription:
       "This documentation provides a reference to the `{{alias}}`. It belongs to the `@medusajs/core-flows` package.",
     frontmatterData: {

www/utils/packages/typedoc-generate-references/src/utils/get-namespaces.ts

@@ -1,4 +1,4 @@
-import { readdirSync } from "fs"
+import { Dirent, readdirSync } from "fs"
 import { rootPathPrefix } from "../constants/general.js"
 import { NamespaceGenerateDetails } from "types"
 import { capitalize, kebabToTitle } from "utils"
@@ -19,40 +19,50 @@ export function getCoreFlowNamespaces(): NamespaceGenerateDetails[] {
     withFileTypes: true,
   })
 
-  directories.forEach((directory) => {
+  const loopDirectories = (dirs: Dirent[], parentDirs: string[] = []) => {
-    if (!directory.isDirectory()) {
+    dirs.forEach((directory) => {
-      return
+      if (!directory.isDirectory()) {
-    }
-
-    const namespaceName = kebabToTitle(directory.name)
-    const pathPattern = `**/packages/core/core-flows/src/${directory.name}/**`
-
-    const namespace: NamespaceGenerateDetails = {
-      name: namespaceName,
-      pathPattern,
-      children: [],
-    }
-
-    const subDirs = readdirSync(path.join(rootFlowsPath, directory.name), {
-      withFileTypes: true,
-    })
-
-    subDirs.forEach((dir) => {
-      if (
-        !dir.isDirectory() ||
-        (dir.name !== "workflows" && dir.name !== "steps")
-      ) {
         return
       }
 
-      namespace.children!.push({
+      const namespaceName = kebabToTitle(directory.name)
-        name: `${capitalize(dir.name)}_${namespaceName}`,
+      const pathPatternPrefix = `**/packages/core/core-flows/src/${
-        pathPattern: `**/packages/core/core-flows/src/${directory.name}/${dir.name}`,
+        parentDirs.length ? `${parentDirs.join("/")}/` : ""
-      })
+      }${directory.name}`
-    })
+      const pathPattern = `${pathPatternPrefix}/**`
 
-    namespaces.push(namespace)
+      const namespace: NamespaceGenerateDetails = {
-  })
+        name: namespaceName,
+        pathPattern,
+        children: [],
+      }
+
+      const subDirs = readdirSync(
+        path.join(rootFlowsPath, ...parentDirs, directory.name),
+        {
+          withFileTypes: true,
+        }
+      )
+
+      subDirs.forEach((dir) => {
+        if (
+          !dir.isDirectory() ||
+          (dir.name !== "workflows" && dir.name !== "steps")
+        ) {
+          return
+        }
+
+        namespace.children!.push({
+          name: `${capitalize(dir.name)}_${namespaceName}`,
+          pathPattern: `${pathPatternPrefix}/${dir.name}/**`,
+        })
+      })
+
+      namespaces.push(namespace)
+    })
+  }
+
+  loopDirectories(directories)
 
   return namespaces
 }