docs-util: fixes to package renames + other options (#9671)

medusajs · Oct 21, 2024 · 34621f5 · 34621f5
1 parent 4829b16
commit 34621f5
Show file tree

Hide file tree

Showing 11 changed files with 200 additions and 131 deletions.
diff --git a/www/utils/packages/typedoc-config/inventory-next.json b/www/utils/packages/typedoc-config/inventory-next.json
@@ -1,11 +1,11 @@
 {
   "$schema": "http://json.schemastore.org/tsconfig",
   "extends": [
-    "../../../../packages/modules/inventory-next/tsconfig.json"
+    "../../../../packages/modules/inventory/tsconfig.json"
   ],
-  "include": ["../../../../packages/modules/inventory-next/src"],
+  "include": ["../../../../packages/modules/inventory/src"],
   "exclude": [
-    "../../../../packages/modules/inventory-next/dist", 
-    "../../../../packages/modules/inventory-next/node_modules"
+    "../../../../packages/modules/inventory/dist", 
+    "../../../../packages/modules/inventory/node_modules"
   ]
 }
diff --git a/www/utils/packages/typedoc-config/stock-location-next.json b/www/utils/packages/typedoc-config/stock-location-next.json
@@ -1,11 +1,11 @@
 {
   "$schema": "http://json.schemastore.org/tsconfig",
   "extends": [
-    "../../../../packages/modules/stock-location-next/tsconfig.json"
+    "../../../../packages/modules/stock-location/tsconfig.json"
   ],
-  "include": ["../../../../packages/modules/stock-location-next/src"],
+  "include": ["../../../../packages/modules/stock-location/src"],
   "exclude": [
-    "../../../../packages/modules/stock-location-next/dist", 
-    "../../../../packages/modules/stock-location-next/node_modules"
+    "../../../../packages/modules/stock-location/dist", 
+    "../../../../packages/modules/stock-location/node_modules"
   ]
 }
diff --git a/www/utils/packages/typedoc-generate-references/src/commands/generate.ts b/www/utils/packages/typedoc-generate-references/src/commands/generate.ts
@@ -40,14 +40,22 @@ export default async function generate(
           outputType: "json",
         })
 
+        const modelReferenceName = `${referenceName}-models`
+
         const modelOptions = getModelOptions({
           moduleName: referenceName,
+          typedocOptions: Object.hasOwn(
+            customModulesOptions,
+            modelReferenceName
+          )
+            ? customModulesOptions[modelReferenceName]
+            : undefined,
         })
 
         try {
           await generateReference({
             options: modelOptions,
-            referenceName: `${referenceName}-models`,
+            referenceName: modelReferenceName,
             outputType: "json",
           })
         } catch (e) {

diff --git a/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts b/www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts
@@ -58,6 +58,7 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     tsConfigName: "js-sdk.json",
     name: "js-sdk",
     enableInternalResolve: true,
+    exclude: [...(baseOptions.exclude || []), "**/dist/**"],
   }),
   "helper-steps": getOptions({
     entryPointPath: "packages/core/core-flows/src/common/index.ts",

diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/js-sdk.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/js-sdk.ts
@@ -37,7 +37,7 @@ const jsSdkOptions: FormattingOptionsType = {
     reflectionDescription:
       "This documentation provides a reference to the `sdk.store.{{alias}}` set of methods used to send requests to Medusa's Store API routes.",
   },
-  "^js_sdk/store/classes/.*Admin": {
+  "^js_sdk/admin/classes/.*Admin": {
     frontmatterData: {
       slug: "/references/js-sdk/admin",
     },
@@ -60,7 +60,7 @@ const jsSdkOptions: FormattingOptionsType = {
     reflectionDescription:
       "This documentation provides a reference to the `sdk.admin.{{alias}}` set of methods used to send requests to Medusa's Admin API routes.",
   },
-  "^js_sdk/store/classes/.*Auth": {
+  "^js_sdk/auth/classes/.*Auth": {
     frontmatterData: {
       slug: "/references/js-sdk/auth",
     },

diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts
@@ -1,4 +1,4 @@
-import { TypeDocOptions } from "typedoc"
+import { ReflectionKind, TypeDocOptions } from "typedoc"
 import { baseOptions } from "./base-options.js"
 import path from "path"
 import { jsonOutputPathPrefix, rootPathPrefix } from "./general.js"
@@ -8,7 +8,7 @@ import {
   customModuleTitles,
   dmlModules,
 } from "./references-details.js"
-import { FormattingOptionType } from "types"
+import { AllowedProjectDocumentsOption, FormattingOptionType } from "types"
 import { kebabToCamel, kebabToPascal, kebabToSnake, kebabToTitle } from "utils"
 import baseSectionsOptions from "./base-section-options.js"
 import mergerCustomOptions from "./merger-custom-options/index.js"
@@ -17,6 +17,39 @@ import {
   getNamespaceNames,
 } from "../utils/get-namespaces.js"
 
+const commonAllowedDocuments = {
+  [ReflectionKind.Variable]: true,
+  [ReflectionKind.Function]: true,
+  [ReflectionKind.Method]: true,
+}
+const allowedProjectDocuments: AllowedProjectDocumentsOption = {
+  dml: commonAllowedDocuments,
+  "helper-steps": commonAllowedDocuments,
+  workflows: commonAllowedDocuments,
+  "js-sdk": {
+    [ReflectionKind.Method]: true,
+    [ReflectionKind.Property]: true,
+  },
+}
+
+modules.forEach((module) => {
+  allowedProjectDocuments[module] = {
+    ...commonAllowedDocuments,
+  }
+})
+
+dmlModules.forEach((module) => {
+  allowedProjectDocuments[`${module}-models`] = {
+    ...commonAllowedDocuments,
+  }
+})
+
+getNamespaceNames(getCoreFlowNamespaces()).forEach((namespace) => {
+  allowedProjectDocuments[namespace] = {
+    ...commonAllowedDocuments,
+  }
+})
+
 const mergerOptions: Partial<TypeDocOptions> = {
   ...baseOptions,
   entryPoints: [path.join(jsonOutputPathPrefix, "*.json")],
@@ -33,17 +66,8 @@ const mergerOptions: Partial<TypeDocOptions> = {
   objectLiteralTypeDeclarationStyle: "component",
   mdxOutput: true,
   maxLevel: 3,
-  allReflectionsHaveOwnDocument: [
-    ...modules,
-    ...dmlModules.map((module) => `${module}-models`),
-    "dml",
-    "helper-steps",
-    "workflows",
-  ],
-  allPropertyReflectionsHaveOwnDocument: ["js-sdk"],
-  allReflectionsHaveOwnDocumentInNamespace: [
-    ...getNamespaceNames(getCoreFlowNamespaces()),
-  ],
+  // @ts-expect-error this is due to a typing issue in typedoc
+  allowedProjectDocuments,
   formatting: {
     "*": {
       showCommentsAsHeader: true,

diff --git a/www/utils/packages/typedoc-generate-references/src/constants/references-details.ts b/www/utils/packages/typedoc-generate-references/src/constants/references-details.ts
@@ -22,6 +22,16 @@ export const customModulesOptions: Record<string, Partial<TypeDocOptions>> = {
       "packages/core/types/src/stock-location/service.ts"
     ),
   },
+  "inventory-next-models": {
+    entryPoints: getEntryPoints(
+      "packages/modules/inventory/src/models/index.ts"
+    ),
+  },
+  "stock-location-next-models": {
+    entryPoints: getEntryPoints(
+      "packages/modules/stock-location/src/models/index.ts"
+    ),
+  },
 }
 
 // a list of modules that now support DML

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/index.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/index.ts
@@ -33,13 +33,6 @@ export function load(app: Application) {
     defaultValue: false,
   })
 
-  app.options.addDeclaration({
-    help: "[Markdown Plugin] Specify module names where all reflections are outputted into seperate files.",
-    name: "allReflectionsHaveOwnDocument",
-    type: ParameterType.Array,
-    defaultValue: [],
-  })
-
   app.options.addDeclaration({
     help: "[Markdown Plugin] Specify module names where property reflections are outputted into seperate files.",
     name: "allPropertyReflectionsHaveOwnDocument",
@@ -48,9 +41,9 @@ export function load(app: Application) {
   })
 
   app.options.addDeclaration({
-    help: "[Markdown Plugin] Specify namespace names where all reflections are outputted into seperate files.",
-    name: "allReflectionsHaveOwnDocumentInNamespace",
-    type: ParameterType.Array,
+    help: "[Markdown Plugin] Specify for each project / module the allowed document types",
+    name: "allowedProjectDocuments",
+    type: ParameterType.Mixed,
     defaultValue: [],
   })
 

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/toc.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/toc.ts
@@ -14,13 +14,15 @@ export default function (theme: MarkdownTheme) {
     function (this: ProjectReflection | DeclarationReflection) {
       const md: string[] = []
 
-      const { hideInPageTOC, allReflectionsHaveOwnDocumentInNamespace } = theme
+      const { hideInPageTOC } = theme
       const { hideTocHeaders, reflectionGroupRename = {} } =
         theme.getFormattingOptionsForLocation()
 
       const isNamespaceVisible =
         this.kind === ReflectionKind.Namespace &&
-        allReflectionsHaveOwnDocumentInNamespace.includes(this.name)
+        theme.getMappings(this as DeclarationReflection)[
+          ReflectionKind.Namespace
+        ]
       const isVisible =
         isNamespaceVisible ||
         this.groups?.some((group) => {