docs: fix page title in reference pagesnot showing + refactor workflows reference (#10537)

* docs: fix references title + refactor workflow reference generation

* update references sidebar

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

@@ -30,9 +30,6 @@ const allowedProjectDocuments: AllowedProjectDocumentsOption = {
     [ReflectionKind.Method]: true,
     [ReflectionKind.Property]: true,
   },
-  "core-flows": {
-    [ReflectionKind.Function]: true,
-  },
 }
 
 modules.forEach((module) => {
@@ -47,7 +44,11 @@ dmlModules.forEach((module) => {
   }
 })
 
-getNamespaceNames(getCoreFlowNamespaces()).forEach((namespace) => {
+const { mainNamespaces: mainCoreFlowNamespaces } = getNamespaceNames(
+  getCoreFlowNamespaces()
+)
+
+mainCoreFlowNamespaces.forEach((namespace) => {
   allowedProjectDocuments[namespace] = {
     ...commonAllowedDocuments,
   }

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

@@ -67,8 +67,23 @@ export function getCoreFlowNamespaces(): NamespaceGenerateDetails[] {
   return namespaces
 }
 
-export function getNamespaceNames(
-  namespaces: NamespaceGenerateDetails[]
-): string[] {
-  return namespaces.map((namespace) => namespace.name)
+export function getNamespaceNames(namespaces: NamespaceGenerateDetails[]): {
+  mainNamespaces: string[]
+  childNamespaces: string[]
+} {
+  const mainNamespaces: string[] = []
+  const childNamespaces: string[] = []
+
+  namespaces.map((namespace) => {
+    mainNamespaces.push(namespace.name)
+    childNamespaces.push(
+      ...(namespace.children?.map((childNamespace) => childNamespace.name) ||
+        [])
+    )
+  })
+
+  return {
+    mainNamespaces,
+    childNamespaces,
+  }
 }

www/utils/packages/typedoc-plugin-custom/src/generate-path-namespaces.ts

@@ -2,10 +2,10 @@ import { minimatch } from "minimatch"
 import {
   Application,
   Comment,
-  Context,
   Converter,
   DeclarationReflection,
   ParameterType,
+  ProjectReflection,
   ReflectionKind,
 } from "typedoc"
 import { NamespaceGenerateDetails } from "types"
@@ -35,17 +35,18 @@ export function load(app: Application) {
       "generatePathNamespaces"
     ) as unknown as NamespaceGenerateDetails[]
 
-    const generatePathNamespaces = (ns: NamespaceGenerateDetails[]) => {
+    const generatePathNamespaces = (
+      ns: NamespaceGenerateDetails[],
+      parent: ProjectReflection | DeclarationReflection = context.project
+    ) => {
       const createdNamespaces: DeclarationReflection[] = []
       ns.forEach((namespace) => {
-        const genNamespace = createNamespace(context, namespace)
+        const genNamespace = createNamespace(parent, namespace)
 
         generatedNamespaces.set(namespace.pathPattern, genNamespace)
 
         if (namespace.children) {
-          generatePathNamespaces(namespace.children).forEach((child) =>
-            genNamespace.addChild(child)
-          )
+          generatePathNamespaces(namespace.children, genNamespace)
         }
 
         createdNamespaces.push(genNamespace)
@@ -102,24 +103,27 @@ export function load(app: Application) {
 
       const namespace = findNamespace(namespaces)
 
-      namespace?.addChild(reflection)
+      if (namespace) {
+        context.project.removeChild(reflection)
+        namespace?.addChild(reflection)
+      }
     }
   )
 }
 
 function createNamespace(
-  context: Context,
+  parent: DeclarationReflection | ProjectReflection,
   namespace: NamespaceGenerateDetails
 ): DeclarationReflection {
-  const genNamespace = context.createDeclarationReflection(
+  const reflection = new DeclarationReflection(
+    namespace.name,
     ReflectionKind.Namespace,
-    void 0,
-    void 0,
-    namespace.name
+    parent
   )
+  parent.addChild(reflection)
 
   if (namespace.description) {
-    genNamespace.comment = new Comment([
+    reflection.comment = new Comment([
       {
         kind: "text",
         text: namespace.description,
@@ -127,5 +131,5 @@ function createNamespace(
     ])
   }
 
-  return genNamespace
+  return reflection
 }

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

@@ -1,9 +1,12 @@
 import { MarkdownTheme } from "../../theme"
 import * as Handlebars from "handlebars"
-import { DocumentReflection, SignatureReflection } from "typedoc"
+import {
+  DocumentReflection,
+  ReflectionKind,
+  SignatureReflection,
+} from "typedoc"
 import { formatWorkflowDiagramComponent } from "../../utils/format-workflow-diagram-component"
-import { getProjectChild } from "utils"
-import { getWorkflowReflectionFromNamespace } from "../../utils/workflow-utils"
+import { findReflectionInNamespaces, getProjectChild } from "utils"
 
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
@@ -81,7 +84,13 @@ function getStep({
       : "step"
 
   const namespaceRefl = theme.project
-    ? getWorkflowReflectionFromNamespace(theme.project, document.name)
+    ? findReflectionInNamespaces(
+        theme.project
+          .getChildrenByKind(ReflectionKind.Module)
+          .find((moduleRef) => moduleRef.name === "core-flows") ||
+          theme.project,
+        document.name
+      )
     : undefined
 
   const associatedReflection =

www/utils/packages/typedoc-plugin-workflows/src/plugin.ts

@@ -15,7 +15,7 @@ import {
 import ts, { SyntaxKind, VariableStatement } from "typescript"
 import { WorkflowManager, WorkflowDefinition } from "@medusajs/orchestration"
 import Helper from "./utils/helper"
-import { isWorkflow, isWorkflowStep } from "utils"
+import { findReflectionInNamespaces, isWorkflow, isWorkflowStep } from "utils"
 import { StepType } from "./types"
 
 type ParsedStep = {
@@ -253,8 +253,10 @@ class WorkflowsPlugin {
           workflowName: workflowVarName,
         })
       } else {
-        const initializerReflection =
-          context.project.getChildByName(initializerName)
+        const initializerReflection = findReflectionInNamespaces(
+          context.project,
+          initializerName
+        )
 
         if (
           !initializerReflection ||

www/utils/packages/typedoc-plugin-workflows/src/utils/helper.ts

@@ -5,7 +5,7 @@ import {
 } from "typedoc"
 import ts from "typescript"
 import { StepModifier, StepType } from "../types"
-import { capitalize } from "utils"
+import { capitalize, findReflectionInNamespaces } from "utils"
 
 /**
  * A class of helper methods.
@@ -173,7 +173,9 @@ export default class Helper {
     project: ProjectReflection
   ): string | undefined {
     // load it from the project
-    const idVarReflection = project.getChildByName(refName)
+    const idVarReflection =
+      project.getChildByName(refName) ||
+      findReflectionInNamespaces(project, refName)
 
     if (
       !idVarReflection ||

www/utils/packages/utils/src/workflow-utils.ts

@@ -1,4 +1,12 @@
-import { ReferenceType, SignatureReflection, SomeType } from "typedoc"
+import {
+  DeclarationReflection,
+  ProjectReflection,
+  ReferenceType,
+  Reflection,
+  ReflectionKind,
+  SignatureReflection,
+  SomeType,
+} from "typedoc"
 
 export function isWorkflow(reflection: SignatureReflection): boolean {
   return (
@@ -60,3 +68,21 @@ function isAllowedType(type: SomeType | undefined): boolean {
       !disallowedIntrinsicTypeNames.includes(type.name))
   )
 }
+
+export function findReflectionInNamespaces(
+  parent: ProjectReflection | DeclarationReflection,
+  childName: string
+): Reflection | undefined {
+  let childReflection: Reflection | undefined
+  parent.getChildrenByKind(ReflectionKind.Namespace).some((namespace) => {
+    childReflection = namespace.getChildByName(childName)
+
+    if (!childReflection) {
+      childReflection = findReflectionInNamespaces(namespace, childName)
+    }
+
+    return childReflection !== undefined
+  })
+
+  return childReflection
+}