From 34621f53a35b486db63522a9b9752a95188b398e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 21 Oct 2024 09:53:47 +0300 Subject: [PATCH] docs-util: fixes to package renames + other options (#9671) --- .../typedoc-config/inventory-next.json | 8 +- .../typedoc-config/stock-location-next.json | 8 +- .../src/commands/generate.ts | 10 +- .../src/constants/custom-options.ts | 1 + .../constants/merger-custom-options/js-sdk.ts | 4 +- .../src/constants/merger-options.ts | 50 +++-- .../src/constants/references-details.ts | 10 + .../src/index.ts | 13 +- .../src/resources/helpers/toc.ts | 6 +- .../src/theme.ts | 208 ++++++++++-------- www/utils/packages/types/lib/index.d.ts | 13 +- 11 files changed, 200 insertions(+), 131 deletions(-) diff --git a/www/utils/packages/typedoc-config/inventory-next.json b/www/utils/packages/typedoc-config/inventory-next.json index bc1600d3ade04..cd6157039bcb7 100644 --- 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" ] } \ No newline at end of file diff --git a/www/utils/packages/typedoc-config/stock-location-next.json b/www/utils/packages/typedoc-config/stock-location-next.json index 3a14032028fba..bdf4642b5c1e7 100644 --- 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" ] } \ No newline at end of file diff --git a/www/utils/packages/typedoc-generate-references/src/commands/generate.ts b/www/utils/packages/typedoc-generate-references/src/commands/generate.ts index 3c374efa3ed1d..9cbe8d521e580 100644 --- 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 index 40a0c283526cd..4970e8d4176b4 100644 --- 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> = { 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 index 186631f41e0b6..057669833ec24 100644 --- 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 index 3d9e1411b47f5..8f8f675e12139 100644 --- 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 = { ...baseOptions, entryPoints: [path.join(jsonOutputPathPrefix, "*.json")], @@ -33,17 +66,8 @@ const mergerOptions: Partial = { 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 index eebc45f1102eb..a51b5eba458c9 100644 --- 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> = { "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 index 14415938ce8e6..bc6c703de3f50 100644 --- 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 index 0291cc903ea28..17781ef1c7ced 100644 --- 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) => { diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/theme.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/theme.ts index 73fd753265199..3fa9c04f4952f 100644 --- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/theme.ts +++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/theme.ts @@ -22,6 +22,7 @@ import { import { formatContents } from "./utils" import type { + AllowedProjectDocumentsOption, FormattingOptionType, FormattingOptionsType, ParameterStyle, @@ -29,9 +30,8 @@ import type { import { Mapping } from "./types" export class MarkdownTheme extends Theme { - allReflectionsHaveOwnDocument!: string[] allPropertyReflectionsHaveOwnDocument!: string[] - allReflectionsHaveOwnDocumentInNamespace: string[] + allowedProjectDocuments: AllowedProjectDocumentsOption entryDocument: string entryPoints!: string[] filenameSeparator!: string @@ -64,14 +64,12 @@ export class MarkdownTheme extends Theme { constructor(renderer: Renderer) { super(renderer) - // prettier-ignore - this.allReflectionsHaveOwnDocument = this.getOption("allReflectionsHaveOwnDocument") as string[] this.allPropertyReflectionsHaveOwnDocument = this.getOption( "allPropertyReflectionsHaveOwnDocument" ) as string[] - this.allReflectionsHaveOwnDocumentInNamespace = this.getOption( - "allReflectionsHaveOwnDocumentInNamespace" - ) as string[] + this.allowedProjectDocuments = this.getOption( + "allowedProjectDocuments" + ) as AllowedProjectDocumentsOption this.entryDocument = this.getOption("entryDocument") as string this.entryPoints = this.getOption("entryPoints") as string[] this.filenameSeparator = this.getOption("filenameSeparator") as string @@ -338,33 +336,52 @@ export class MarkdownTheme extends Theme { return parents } - getAllReflectionsHaveOwnDocument( - reflection: DeclarationReflection, - checkProperties?: boolean - ): boolean { + getAllowedReflectionDocuments(reflection: DeclarationReflection) { + const documents = { + [ReflectionKind.Module]: true, + [ReflectionKind.Namespace]: true, + [ReflectionKind.Enum]: true, + [ReflectionKind.Class]: true, + [ReflectionKind.Interface]: true, + [ReflectionKind.TypeAlias]: true, + [ReflectionKind.Variable]: false, + [ReflectionKind.Function]: false, + [ReflectionKind.Method]: false, + [ReflectionKind.Property]: false, + } + + let options: Record | undefined + const moduleParents = this.getParentsOfKind( reflection, ReflectionKind.Module - ) + ).reverse() // projects come last, this changes the direction to give projects higher priority const namespaceParents = this.getParentsOfKind( reflection, ReflectionKind.Namespace ) - if (checkProperties) { - return moduleParents.some((parent) => - this.allPropertyReflectionsHaveOwnDocument.includes(parent.name) - ) - } + moduleParents.some((parent) => { + if (!Object.hasOwn(this.allowedProjectDocuments, parent.name)) { + return false + } - return ( - moduleParents.some((parent) => - this.allReflectionsHaveOwnDocument.includes(parent.name) - ) || - namespaceParents.some((parent) => - this.allReflectionsHaveOwnDocumentInNamespace.includes(parent.name) - ) - ) + options = this.allowedProjectDocuments[parent.name] + return true + }) || + namespaceParents.some((parent) => { + if (!Object.hasOwn(this.allowedProjectDocuments, parent.name)) { + return false + } + + options = this.allowedProjectDocuments[parent.name] + return true + }) + + return { + ...documents, + ...(options || {}), + } } getFileNameSeparator(pathPrefix: string): string { @@ -376,8 +393,11 @@ export class MarkdownTheme extends Theme { reflection: DeclarationReflection, directoryPrefix?: string ): Mapping[] { - return [ - { + const allowedDocuments = this.getAllowedReflectionDocuments(reflection) + const mappings: Mapping[] = [] + + if (allowedDocuments[ReflectionKind.Module]) { + mappings.push({ kind: [ReflectionKind.Module], modifiers: { has: [], @@ -386,8 +406,10 @@ export class MarkdownTheme extends Theme { isLeaf: false, directory: path.join(directoryPrefix || "", "modules"), template: this.getReflectionTemplate(), - }, - { + }) + } + if (allowedDocuments[ReflectionKind.Namespace]) { + mappings.push({ kind: [ReflectionKind.Namespace], modifiers: { has: [], @@ -396,8 +418,10 @@ export class MarkdownTheme extends Theme { isLeaf: false, directory: path.join(directoryPrefix || ""), template: this.getReflectionTemplate(), - }, - { + }) + } + if (allowedDocuments[ReflectionKind.Enum]) { + mappings.push({ kind: [ReflectionKind.Enum], modifiers: { has: [], @@ -406,8 +430,10 @@ export class MarkdownTheme extends Theme { isLeaf: false, directory: path.join(directoryPrefix || "", "enums"), template: this.getReflectionTemplate(), - }, - { + }) + } + if (allowedDocuments[ReflectionKind.Class]) { + mappings.push({ kind: [ReflectionKind.Class], modifiers: { has: [], @@ -416,8 +442,10 @@ export class MarkdownTheme extends Theme { isLeaf: false, directory: path.join(directoryPrefix || "", "classes"), template: this.getReflectionTemplate(), - }, - { + }) + } + if (allowedDocuments[ReflectionKind.Interface]) { + mappings.push({ kind: [ReflectionKind.Interface], modifiers: { has: [], @@ -426,8 +454,11 @@ export class MarkdownTheme extends Theme { isLeaf: false, directory: path.join(directoryPrefix || "", "interfaces"), template: this.getReflectionTemplate(), - }, - { + }) + } + + if (allowedDocuments[ReflectionKind.TypeAlias]) { + mappings.push({ kind: [ReflectionKind.TypeAlias], modifiers: { has: [], @@ -436,56 +467,59 @@ export class MarkdownTheme extends Theme { isLeaf: true, directory: path.join(directoryPrefix || "", "types"), template: this.getReflectionMemberTemplate(), - }, - ...(this.getAllReflectionsHaveOwnDocument(reflection) - ? [ - { - kind: [ReflectionKind.Variable], - modifiers: { - has: [], - not: [], - }, - isLeaf: true, - directory: path.join(directoryPrefix || "", "variables"), - template: this.getReflectionMemberTemplate(), - }, - { - kind: [ReflectionKind.Function], - modifiers: { - has: [], - not: [], - }, - isLeaf: true, - directory: path.join(directoryPrefix || "", "functions"), - template: this.getReflectionMemberTemplate(), - }, - { - kind: [ReflectionKind.Method], - modifiers: { - has: [], - not: [], - }, - isLeaf: true, - directory: path.join(directoryPrefix || "", "methods"), - template: this.getReflectionMemberTemplate(), - }, - ] - : []), - ...(this.getAllReflectionsHaveOwnDocument(reflection, true) - ? [ - { - kind: [ReflectionKind.Property], - modifiers: { - has: [], - not: [], - }, - isLeaf: true, - directory: path.join(directoryPrefix || "", "properties"), - template: this.getReflectionMemberTemplate(), - }, - ] - : []), - ] + }) + } + + if (allowedDocuments[ReflectionKind.Variable]) { + mappings.push({ + kind: [ReflectionKind.Variable], + modifiers: { + has: [], + not: [], + }, + isLeaf: true, + directory: path.join(directoryPrefix || "", "variables"), + template: this.getReflectionMemberTemplate(), + }) + } + if (allowedDocuments[ReflectionKind.Function]) { + mappings.push({ + kind: [ReflectionKind.Function], + modifiers: { + has: [], + not: [], + }, + isLeaf: true, + directory: path.join(directoryPrefix || "", "functions"), + template: this.getReflectionMemberTemplate(), + }) + } + if (allowedDocuments[ReflectionKind.Method]) { + mappings.push({ + kind: [ReflectionKind.Method], + modifiers: { + has: [], + not: [], + }, + isLeaf: true, + directory: path.join(directoryPrefix || "", "methods"), + template: this.getReflectionMemberTemplate(), + }) + } + if (allowedDocuments[ReflectionKind.Property]) { + mappings.push({ + kind: [ReflectionKind.Property], + modifiers: { + has: [], + not: [], + }, + isLeaf: true, + directory: path.join(directoryPrefix || "", "properties"), + template: this.getReflectionMemberTemplate(), + }) + } + + return mappings } /** diff --git a/www/utils/packages/types/lib/index.d.ts b/www/utils/packages/types/lib/index.d.ts index f804f8d5e6a63..58c96953948f4 100644 --- a/www/utils/packages/types/lib/index.d.ts +++ b/www/utils/packages/types/lib/index.d.ts @@ -86,6 +86,10 @@ export type FormattingOptionType = { workflowDiagramComponent?: string } +export type AllowedProjectDocumentsOption = { + [k: string]: Record +} + export declare module "typedoc" { declare interface TypeDocOptionMap { /** @@ -136,14 +140,7 @@ export declare module "typedoc" { * @defaultValue false */ namedAnchors: boolean - /** - * [Markdown Plugin] Specify module names where all reflections are outputted into seperate files. - */ - allReflectionsHaveOwnDocument: string[] - /** - * [Markdown Plugin] Specify module names where property reflections are outputted into seperate files. - */ - allPropertyReflectionsHaveOwnDocument: string[] + allowedProjectDocuments: AllowedProjectDocumentsOption /** * [Markdown Plugin] Separator used to format filenames. * @defaultValue "."