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,25 +37,30 @@ 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[] = []
 
+    const readItemsFromChildDirs = async (type: "Steps" | "Workflows") => {
+      const childNamespaceBasePath = path.join(
+        basePath,
+        directory.name,
+        `${type}_${directory.name}`,
+        "functions"
+      )
+
+      if (!existsSync(childNamespaceBasePath)) {
+        return
+      }
+      const childDirs = readdirSync(childNamespaceBasePath, {
+        withFileTypes: true,
+      })
+
       for (const childDir of childDirs) {
         if (!childDir.isDirectory()) {
           continue
         }
 
-      const childDirPath = path.join(namespaceBasePath, childDir.name)
+        const childDirPath = path.join(childNamespaceBasePath, childDir.name)
         const childFile = readdirSync(childDirPath)
 
         if (!childFile.length) {
@@ -76,6 +81,10 @@ export default async function getCoreFlowsRefSidebarChildren(): Promise<
           }
         }
       }
+    }
+
+    await readItemsFromChildDirs("Steps")
+    await readItemsFromChildDirs("Workflows")
 
     if (workflowItems.length || stepItems.length) {
       const item: ItemsToAdd = {

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,13 +19,17 @@ export function getCoreFlowNamespaces(): NamespaceGenerateDetails[] {
     withFileTypes: true,
   })
 
-  directories.forEach((directory) => {
+  const loopDirectories = (dirs: Dirent[], parentDirs: string[] = []) => {
+    dirs.forEach((directory) => {
       if (!directory.isDirectory()) {
         return
       }
 
       const namespaceName = kebabToTitle(directory.name)
-    const pathPattern = `**/packages/core/core-flows/src/${directory.name}/**`
+      const pathPatternPrefix = `**/packages/core/core-flows/src/${
+        parentDirs.length ? `${parentDirs.join("/")}/` : ""
+      }${directory.name}`
+      const pathPattern = `${pathPatternPrefix}/**`
 
       const namespace: NamespaceGenerateDetails = {
         name: namespaceName,
@@ -33,9 +37,12 @@ export function getCoreFlowNamespaces(): NamespaceGenerateDetails[] {
         children: [],
       }
 
-    const subDirs = readdirSync(path.join(rootFlowsPath, directory.name), {
+      const subDirs = readdirSync(
+        path.join(rootFlowsPath, ...parentDirs, directory.name),
+        {
           withFileTypes: true,
-    })
+        }
+      )
 
       subDirs.forEach((dir) => {
         if (
@@ -47,12 +54,15 @@ export function getCoreFlowNamespaces(): NamespaceGenerateDetails[] {
 
         namespace.children!.push({
           name: `${capitalize(dir.name)}_${namespaceName}`,
-        pathPattern: `**/packages/core/core-flows/src/${directory.name}/${dir.name}`,
+          pathPattern: `${pathPatternPrefix}/${dir.name}/**`,
         })
       })
 
       namespaces.push(namespace)
     })
+  }
+
+  loopDirectories(directories)
 
   return namespaces
 }