chore(docs): Generated References (#5602)

Generated the following references:
- `pricing`
- `product`

Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>
Co-authored-by: Shahed Nasser <27354907+shahednasser@users.noreply.github.com>

docs-util/packages/typedoc-config/_base.js

@@ -6,13 +6,14 @@ const pathPrefix = path.join(__dirname, "..", "..", "..")
 /** @type {import('typedoc').TypeDocOptions} */
 module.exports = {
   // extends: [typedocConfig],
-  plugin: ["typedoc-plugin-markdown-medusa"],
+  plugin: ["typedoc-plugin-markdown-medusa", "typedoc-plugin-custom"],
   readme: "none",
   eslintPathName: path.join(
     pathPrefix,
     "www/packages/eslint-config-docs/content.js"
   ),
   pluginsResolvePath: path.join(pathPrefix, "www"),
+  exclude: [path.join(pathPrefix, "node_modules/**")],
   // Uncomment this when debugging
   // showConfig: true,
 }

docs-util/packages/typedoc-config/_modules.js

@@ -79,12 +79,7 @@ module.exports = ({
     entryPointStrategy: "expand",
     hideInPageTOC: true,
     hideBreadcrumbs: true,
-    plugin: [
-      ...globalTypedocOptions.plugin,
-      "typedoc-plugin-custom",
-      "typedoc-plugin-rename-defaults",
-      "typedoc-plugin-frontmatter",
-    ],
+    plugin: [...globalTypedocOptions.plugin, "typedoc-plugin-rename-defaults"],
     formatting,
     allReflectionsHaveOwnDocument: true,
     objectLiteralTypeDeclarationStyle: "component",

docs-util/packages/typedoc-config/entities.js

@@ -11,13 +11,9 @@ module.exports = {
   tsconfig: path.join(__dirname, "extended-tsconfig", "medusa.json"),
   name: "Entities Reference",
   indexTitle: "Entities Reference",
-  entryDocument: "_index.mdx",
+  entryDocument: "index.mdx",
   hideInPageTOC: true,
   hideBreadcrumbs: true,
-  plugin: [...globalTypedocOptions.plugin, "typedoc-plugin-frontmatter"],
-  frontmatterData: {
-    displayed_sidebar: "entitiesSidebar",
-  },
   formatting: {
     "*": {
       showCommentsAsHeader: true,
@@ -34,8 +30,15 @@ module.exports = {
         Constructors: false,
         Methods: false,
       },
+      frontmatterData: {
+        displayed_sidebar: "entitiesSidebar",
+      },
+    },
+    "(Order|Swap|Cart|LineItem)": {
+      maxLevel: 1,
     },
   },
   objectLiteralTypeDeclarationStyle: "component",
   mdxOutput: true,
+  maxLevel: 2,
 }

docs-util/packages/typedoc-config/js-client.js

@@ -28,6 +28,14 @@ const defaultFormattingOptions = {
   },
 }
 
+const classesFormattingOptions = {
+  ...defaultFormattingOptions,
+  frontmatterData: {
+    ...defaultFormattingOptions.frontmatterData,
+    slug: "/references/js-client/{{alias}}",
+  },
+}
+
 /** @type {import('typedoc').TypeDocOptions} */
 module.exports = {
   ...globalTypedocOptions,
@@ -36,26 +44,32 @@ module.exports = {
   tsconfig: path.join(__dirname, "extended-tsconfig", "js-client.json"),
   name: "JS Client Reference",
   indexTitle: "JS Client Reference",
-  entryDocument: "_index.mdx",
+  entryDocument: "index.mdx",
   hideInPageTOC: true,
   hideBreadcrumbs: true,
-  plugin: [
-    ...globalTypedocOptions.plugin,
-    "typedoc-plugin-rename-defaults",
-    "typedoc-plugin-custom",
-  ],
+  plugin: [...globalTypedocOptions.plugin, "typedoc-plugin-rename-defaults"],
   exclude: [
+    ...globalTypedocOptions.exclude,
     path.join(pathPrefix, "packages/medusa-js/src/resources/base.ts"),
-    path.join(pathPrefix, "node_modules/**"),
   ],
   internalModule: "internal",
   formatting: {
     "*": defaultFormattingOptions,
-    "^classes/": {
-      ...defaultFormattingOptions,
-      frontmatterData: {
-        ...defaultFormattingOptions.frontmatterData,
-        slug: "/references/js-client/{{alias}}",
+    "^classes/": classesFormattingOptions,
+    AdminOrdersResource: {
+      maxLevel: 2,
+    },
+    internal: {
+      maxLevel: 1,
+    },
+    "internal/modules/internal": {
+      reflectionGroups: {
+        ...defaultFormattingOptions.reflectionGroups,
+        "Type Aliases": false,
+        Enumerations: false,
+        Classes: false,
+        Functions: false,
+        Interfaces: false,
       },
     },
   },
@@ -63,4 +77,7 @@ module.exports = {
   mdxOutput: true,
   maxLevel: 4,
   ignoreApi: true,
+  outputModules: false,
+  outputNamespace: false,
+  excludeReferences: true,
 }

docs-util/packages/typedoc-config/pricing.js

@@ -7,17 +7,11 @@ module.exports = modulesConfig({
   moduleName: "Pricing Module Reference",
   documentsToFormat: [
     {
-      pattern: "IPricingModuleService.md",
+      pattern: "*",
+      useDefaults: true,
       additionalFormatting: {
-        reflectionDescription:
-          "This section of the documentation provides a reference to the `IPricingModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Pricing Module.",
         frontmatterData: {
           displayed_sidebar: "pricingReference",
-          badge: {
-            variant: "orange",
-            text: "Beta",
-          },
-          slug: "/references/pricing",
         },
       },
     },
@@ -43,11 +37,17 @@ module.exports = modulesConfig({
       },
     },
     {
-      pattern: "*",
-      useDefaults: true,
+      pattern: "IPricingModuleService.md",
       additionalFormatting: {
+        reflectionDescription:
+          "This section of the documentation provides a reference to the `IPricingModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Pricing Module.",
         frontmatterData: {
           displayed_sidebar: "pricingReference",
+          badge: {
+            variant: "orange",
+            text: "Beta",
+          },
+          slug: "/references/pricing",
         },
       },
     },

docs-util/packages/typedoc-config/product.js

@@ -7,17 +7,11 @@ module.exports = modulesConfig({
   moduleName: "Product Module Reference",
   documentsToFormat: [
     {
-      pattern: "IProductModuleService.md",
+      pattern: "*",
+      useDefaults: true,
       additionalFormatting: {
-        reflectionDescription:
-          "This section of the documentation provides a reference to the `IProductModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Product Module.",
         frontmatterData: {
           displayed_sidebar: "productReference",
-          badge: {
-            variant: "orange",
-            text: "Beta",
-          },
-          slug: "/references/product",
         },
       },
     },
@@ -43,11 +37,17 @@ module.exports = modulesConfig({
       },
     },
     {
-      pattern: "*",
-      useDefaults: true,
+      pattern: "IProductModuleService.md",
       additionalFormatting: {
+        reflectionDescription:
+          "This section of the documentation provides a reference to the `IProductModuleService` interface’s methods. This is the interface developers use to use the functionalities provided by the Product Module.",
         frontmatterData: {
           displayed_sidebar: "productReference",
+          badge: {
+            variant: "orange",
+            text: "Beta",
+          },
+          slug: "/references/product",
         },
       },
     },

docs-util/packages/typedoc-config/services.js

@@ -14,4 +14,30 @@ module.exports = {
   entryDocument: "index.md",
   hideInPageTOC: true,
   hideBreadcrumbs: true,
+  formatting: {
+    "*": {
+      showCommentsAsHeader: true,
+      sections: {
+        member_sources_definedIn: false,
+        reflection_hierarchy: false,
+        member_sources_inheritedFrom: false,
+        member_sources_implementationOf: false,
+        reflection_implementedBy: false,
+        member_signature_sources: false,
+        reflection_callable: false,
+        reflection_indexable: false,
+      },
+      parameterStyle: "component",
+      parameterComponent: "ParameterTypes",
+      mdxImports: [
+        `import ParameterTypes from "@site/src/components/ParameterTypes"`,
+      ],
+      frontmatterData: {
+        displayed_sidebar: "servicesSidebar",
+      },
+    },
+  },
+  objectLiteralTypeDeclarationStyle: "component",
+  mdxOutput: true,
+  maxLevel: 1,
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/index.ts

@@ -116,5 +116,19 @@ export function load(app: Application) {
     type: ParameterType.Number,
     defaultValue: 3,
   })
+
+  app.options.addDeclaration({
+    help: "[Markdown Plugin] Whether to output modules file for namespaces.",
+    name: "outputNamespace",
+    type: ParameterType.Boolean,
+    defaultValue: true,
+  })
+
+  app.options.addDeclaration({
+    help: "[Markdown Plugin] Whether to output module files.",
+    name: "outputModules",
+    type: ParameterType.Boolean,
+    defaultValue: true,
+  })
 }
 export { MarkdownTheme }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/declaration-title.ts

@@ -57,7 +57,9 @@ export default function (theme: MarkdownTheme) {
         this.defaultValue &&
         this.defaultValue !== "..."
       ) {
-        md.push(` = \`${stripLineBreaks(stripComments(this.defaultValue))}\``)
+        md.push(
+          ` = \`${stripLineBreaks(stripComments(`${this.defaultValue}`))}\``
+        )
       }
       return md.join("")
     }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/parameter-component.ts

@@ -8,11 +8,12 @@ export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "parameterComponent",
     function (this: ReflectionParameterType[]) {
-      const { parameterComponent } = theme.getFormattingOptionsForLocation()
+      const { parameterComponent, maxLevel } =
+        theme.getFormattingOptionsForLocation()
       const parameters = this.reduce(
         (acc: ReflectionParameterType[], current) => parseParams(current, acc),
         []
-      ).map((parameter) => reflectionComponentFormatter(parameter, 1))
+      ).map((parameter) => reflectionComponentFormatter(parameter, 1, maxLevel))
 
       return `<${parameterComponent} parameters={${JSON.stringify(
         parameters,

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/returns.ts

@@ -24,7 +24,7 @@ function getReturnFromType(
   theme: MarkdownTheme,
   reflection: SignatureReflection
 ) {
-  const { parameterStyle, parameterComponent } =
+  const { parameterStyle, parameterComponent, maxLevel } =
     theme.getFormattingOptionsForLocation()
 
   if (!reflection.type) {
@@ -35,7 +35,8 @@ function getReturnFromType(
     reflection.type,
     reflection.project || theme.project,
     reflection.comment,
-    1
+    1,
+    maxLevel
   )
 
   if (parameterStyle === "component") {
@@ -73,7 +74,7 @@ function formatReturnAsList(componentItems: Parameter[], level = 1): string {
 
 function getReturnFromComment(theme: MarkdownTheme, comment: Comment) {
   const md: string[] = []
-  const { parameterStyle, parameterComponent } =
+  const { parameterStyle, parameterComponent, maxLevel } =
     theme.getFormattingOptionsForLocation()
 
   if (comment.blockTags?.length) {
@@ -87,7 +88,7 @@ function getReturnFromComment(theme: MarkdownTheme, comment: Comment) {
             commentPart.target instanceof DeclarationReflection
           ) {
             const content = commentPart.target.children?.map((childItem) =>
-              reflectionFormatter(childItem, parameterStyle, 1)
+              reflectionFormatter(childItem, parameterStyle, 1, maxLevel)
             )
             result +=
               parameterStyle === "component"

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type-declaration-object-literal.ts

@@ -10,7 +10,8 @@ export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "typeDeclarationMembers",
     function (this: DeclarationReflection[]) {
-      const { parameterComponent } = theme.getFormattingOptionsForLocation()
+      const { parameterComponent, maxLevel } =
+        theme.getFormattingOptionsForLocation()
       const comments = this.map(
         (param) => !!param.comment?.hasVisibleComponent()
       )
@@ -29,7 +30,11 @@ export default function (theme: MarkdownTheme) {
           break
         }
         case "component": {
-          result = getComponentMarkdownContent(properties, parameterComponent)
+          result = getComponentMarkdownContent(
+            properties,
+            parameterComponent,
+            maxLevel
+          )
           break
         }
         case "table": {
@@ -52,10 +57,11 @@ function getListMarkdownContent(properties: DeclarationReflection[]) {
 
 function getComponentMarkdownContent(
   properties: DeclarationReflection[],
-  parameterComponent?: string
+  parameterComponent?: string,
+  maxLevel?: number | undefined
 ) {
   const parameters = properties.map((property) =>
-    reflectionFormatter(property, "component")
+    reflectionFormatter(property, "component", 1, maxLevel)
   )
 
   return `<${parameterComponent} parameters={${JSON.stringify(

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type-parameter-component.ts

@@ -7,9 +7,10 @@ export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "typeParameterComponent",
     function (this: TypeParameterReflection[]) {
-      const { parameterComponent } = theme.getFormattingOptionsForLocation()
+      const { parameterComponent, maxLevel } =
+        theme.getFormattingOptionsForLocation()
       const parameters = this.map((parameter) =>
-        reflectionComponentFormatter(parameter, 1)
+        reflectionComponentFormatter(parameter, 1, maxLevel)
       )
 
       return `<${parameterComponent} parameters={${JSON.stringify(

docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts

@@ -48,6 +48,8 @@ export class MarkdownTheme extends Theme {
   objectLiteralTypeDeclarationStyle: ObjectLiteralDeclarationStyle
   formattingOptions: FormattingOptionsType
   mdxOutput: boolean
+  outputNamespace: boolean
+  outputModules: boolean
 
   project?: ProjectReflection
   reflection?: DeclarationReflection
@@ -87,6 +89,8 @@ export class MarkdownTheme extends Theme {
       "formatting"
     ) as FormattingOptionsType
     this.mdxOutput = this.getOption("mdxOutput") as boolean
+    this.outputNamespace = this.getOption("outputNamespace") as boolean
+    this.outputModules = this.getOption("outputModules") as boolean
     MarkdownTheme.MAX_LEVEL = this.getOption("maxLevel") as number
 
     this.listenTo(this.owner, {
@@ -306,14 +310,14 @@ export class MarkdownTheme extends Theme {
         directory: path.join(directoryPrefix || "", "interfaces"),
         template: this.getReflectionTemplate(),
       },
+      {
+        kind: [ReflectionKind.TypeAlias],
+        isLeaf: true,
+        directory: path.join(directoryPrefix || "", "types"),
+        template: this.getReflectionMemberTemplate(),
+      },
       ...(this.allReflectionsHaveOwnDocument
         ? [
-            {
-              kind: [ReflectionKind.TypeAlias],
-              isLeaf: true,
-              directory: path.join(directoryPrefix || "", "types"),
-              template: this.getReflectionMemberTemplate(),
-            },
             {
               kind: [ReflectionKind.Variable],
               isLeaf: true,
@@ -382,20 +386,14 @@ export class MarkdownTheme extends Theme {
       return {}
     }
 
-    const optionKey =
-      Object.keys(this.formattingOptions).find((key) => {
-        if (key === "*") {
-          return false
-        }
+    const applicableOptions: FormattingOptionType[] = []
 
-        const keyPattern = new RegExp(key)
-        if (keyPattern.test(this.location)) {
-          return true
-        }
-      }) || "*"
+    Object.keys(this.formattingOptions).forEach((key) => {
+      if (key === "*" || new RegExp(key).test(this.location)) {
+        applicableOptions.push(this.formattingOptions[key])
+      }
+    })
 
-    return optionKey in this.formattingOptions
-      ? this.formattingOptions[optionKey]
-      : {}
+    return Object.assign({}, ...applicableOptions)
   }
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts

@@ -20,13 +20,14 @@ const ALLOWED_KINDS: ReflectionKind[] = [
 export default function reflectionFormatter(
   reflection: ReflectionParameterType,
   type: ParameterStyle = "table",
-  level = 1
+  level = 1,
+  maxLevel?: number | undefined
 ): string | Parameter {
   switch (type) {
     case "list":
       return reflectionListFormatter(reflection, level)
     case "component":
-      return reflectionComponentFormatter(reflection, level)
+      return reflectionComponentFormatter(reflection, level, maxLevel)
     case "table":
       return reflectionTableFormatter(reflection)
     default:
@@ -36,7 +37,8 @@ export default function reflectionFormatter(
 
 export function reflectionListFormatter(
   reflection: ReflectionParameterType,
-  level = 1
+  level = 1,
+  maxLevel?: number | undefined
 ): string {
   const prefix = `${Array(level - 1)
     .fill("\t")
@@ -63,7 +65,7 @@ export function reflectionListFormatter(
 
   if (
     (reflection.type || hasChildren) &&
-    level + 1 <= MarkdownTheme.MAX_LEVEL
+    level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
   ) {
     const children = hasChildren
       ? reflection.children
@@ -89,7 +91,8 @@ export function reflectionListFormatter(
 
 export function reflectionComponentFormatter(
   reflection: ReflectionParameterType,
-  level = 1
+  level = 1,
+  maxLevel?: number | undefined
 ): Parameter {
   const defaultValue = getDefaultValue(reflection) || ""
   const optional =
@@ -114,7 +117,7 @@ export function reflectionComponentFormatter(
 
   if (
     (reflection.type || hasChildren) &&
-    level + 1 <= MarkdownTheme.MAX_LEVEL
+    level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
   ) {
     const children = hasChildren
       ? reflection.children
@@ -124,7 +127,7 @@ export function reflectionComponentFormatter(
       ?.filter((childItem) => childItem.kindOf(ALLOWED_KINDS))
       .forEach((childItem) => {
         componentItem.children?.push(
-          reflectionComponentFormatter(childItem, level + 1)
+          reflectionComponentFormatter(childItem, level + 1, maxLevel)
         )
       })
   }

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/return-reflection-formatter.ts

@@ -18,7 +18,8 @@ export function returnReflectionComponentFormatter(
   reflectionType: SomeType,
   project: ProjectReflection,
   comment?: Comment,
-  level = 1
+  level = 1,
+  maxLevel?: number | undefined
 ): Parameter[] {
   const typeName = getType(reflectionType, "object", false)
   const type = getType(reflectionType, "object")
@@ -46,14 +47,15 @@ export function returnReflectionComponentFormatter(
       })
       if (
         !isOnlyVoid(reflectionType.typeArguments) &&
-        level + 1 <= MarkdownTheme.MAX_LEVEL
+        level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
       ) {
         reflectionType.typeArguments.forEach((typeArg) => {
           const typeArgComponent = returnReflectionComponentFormatter(
             typeArg,
             project,
             undefined,
-            level + 1
+            level + 1,
+            maxLevel
           )
           if (typeArgComponent.length) {
             componentItem[parentKey - 1].children?.push(...typeArgComponent)
@@ -69,7 +71,8 @@ export function returnReflectionComponentFormatter(
             componentItem.push(
               reflectionComponentFormatter(
                 childItem as DeclarationReflection,
-                level
+                level,
+                maxLevel
               )
             )
           })
@@ -77,7 +80,8 @@ export function returnReflectionComponentFormatter(
           componentItem.push(
             reflectionComponentFormatter(
               reflection as DeclarationReflection,
-              level
+              level,
+              maxLevel
             )
           )
         }
@@ -103,12 +107,13 @@ export function returnReflectionComponentFormatter(
       featureFlag: Handlebars.helpers.featureFlag(comment),
       children: [],
     })
-    if (level + 1 <= MarkdownTheme.MAX_LEVEL) {
+    if (level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)) {
       const elementTypeItem = returnReflectionComponentFormatter(
         reflectionType.elementType,
         project,
         undefined,
-        level + 1
+        level + 1,
+        maxLevel
       )
       if (elementTypeItem.length) {
         componentItem[parentKey - 1].children?.push(...elementTypeItem)
@@ -140,13 +145,14 @@ export function returnReflectionComponentFormatter(
     } else {
       pushTo = componentItem
     }
-    if (level + 1 <= MarkdownTheme.MAX_LEVEL) {
+    if (level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)) {
       reflectionType.elements.forEach((element) => {
         const elementTypeItem = returnReflectionComponentFormatter(
           element,
           project,
           undefined,
-          level + 1
+          level + 1,
+          maxLevel
         )
         if (elementTypeItem.length) {
           pushTo.push(...elementTypeItem)

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/type-utils.ts

@@ -128,7 +128,7 @@ export function getDeclarationType(model: DeclarationReflection): string {
           obj.type ? getType(obj.type) : escapeChars(obj.toString())
         } ${
           obj.defaultValue && obj.defaultValue !== "..."
-            ? `= ${escapeChars(obj.defaultValue)}`
+            ? `= ${escapeChars(`${obj.defaultValue}`)}`
             : ""
         }`
       })
@@ -136,7 +136,7 @@ export function getDeclarationType(model: DeclarationReflection): string {
       types ? types.join("; ") : ""
     } }${
       model.defaultValue && model.defaultValue !== "..."
-        ? `= ${escapeChars(model.defaultValue)}`
+        ? `= ${escapeChars(`${model.defaultValue}`)}`
         : ""
     }`
   }