asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(docs): DML API Reference (#7863)

Browse Source 
* added dml options

* added tsdocs + configurations
This commit is contained in:
Shahed Nasser
2024-07-01 10:21:56 +03:00
committed by GitHub
parent 9ded63cc62
commit 72f7500c84
20 changed files with 746 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts
+15 -28
View File
@@ -16,6 +16,16 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
name: "auth-provider",
parentIgnore: true,
}),
dml: getOptions({
entryPointPath: [
"packages/core/utils/src/dml/entity-builder.ts",
"packages/core/utils/src/dml/entity.ts",
"packages/core/utils/src/dml/properties/base.ts",
],
tsConfigName: "utils.json",
name: "dml",
generateNamespaces: true,
}),
file: getOptions({
entryPointPath: "packages/core/utils/src/file/abstract-file-provider.ts",
tsConfigName: "utils.json",
@@ -28,29 +38,11 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
name: "fulfillment-provider",
parentIgnore: true,
}),
"js-client": getOptions({
entryPointPath: "packages/medusa-js/src/resources",
tsConfigName: "js-client.json",
name: "js-client",
plugin: ["typedoc-plugin-rename-defaults"],
exclude: [
...(baseOptions.exclude || []),
path.join(rootPathPrefix, "packages/medusa-js/src/resources/base.ts"),
],
ignoreApi: true,
}),
"medusa-config": getOptions({
entryPointPath: "packages/core/types/src/common/config-module.ts",
tsConfigName: "types.json",
name: "medusa-config",
}),
"medusa-react": getOptions({
entryPointPath: "packages/medusa-react/src/index.ts",
tsConfigName: "medusa-react.json",
name: "medusa-react",
generateNamespaces: true,
ignoreApi: true,
}),
medusa: getOptions({
entryPointPath: "packages/medusa/src/index.js",
tsConfigName: "medusa.json",
@@ -96,11 +88,6 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
tsConfigName: "utils.json",
name: "search",
}),
services: getOptions({
entryPointPath: "packages/medusa/src/services/index.ts",
tsConfigName: "medusa.json",
name: "services",
}),
"tax-provider": getOptions({
entryPointPath: "packages/core/types/src/tax/provider.ts",
tsConfigName: "types.json",
@@ -117,11 +104,6 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
...modules.map((moduleName) => `**/${moduleName}/**/*.ts`),
],
}),
workflows: getOptions({
entryPointPath: "packages/core/workflows-sdk/src/utils/composer/index.ts",
tsConfigName: "workflows.json",
name: "workflows",
}),
utils: getOptions({
entryPointPath: "packages/core/utils/src/index.ts",
tsConfigName: "utils.json",
@@ -146,6 +128,11 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
"**/totals/**",
],
}),
workflows: getOptions({
entryPointPath: "packages/core/workflows-sdk/src/utils/composer/index.ts",
tsConfigName: "workflows.json",
name: "workflows",
}),
}
export default customOptions
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/dml.ts
+124
View File
@@ -0,0 +1,124 @@
import { FormattingOptionsType } from "types"
import baseSectionsOptions from "../base-section-options.js"
const dmlOptions: FormattingOptionsType = {
"^dml": {
expandMembers: true,
sections: {
...baseSectionsOptions,
member_getterSetter: false,
member_returns: false,
},
},
"^modules/dml/page\\.mdx": {
reflectionDescription:
"This section of the documentation provides an API reference to the property types and methods used to create a data model.",
reflectionGroups: {
Classes: false,
Variables: false,
Properties: false,
Modules: false,
},
frontmatterData: {
slug: "/references/data-model",
},
reflectionTitle: {
fullReplacement: "Data Models API Reference",
},
hideTocHeaders: true,
},
"^dml/.*define": {
frontmatterData: {
slug: "/references/data-model/define",
},
reflectionTitle: {
suffix: "Method - API Reference",
},
},
"^dml/.*Property_Types/page\\.mdx": {
frontmatterData: {
slug: "/references/data-model/property-types",
},
reflectionDescription:
"The following methods are used to define the type of a property in a data model.",
reflectionTitle: {
suffix: "- API Reference",
},
},
"^dml/Property_Types": {
frontmatterData: {
slug: "/references/data-model/property-types/{{alias-lower}}",
sidebar_label: "{{alias}}",
},
reflectionTitle: {
suffix: "Property Method - API Reference",
},
},
"^dml/.*Relationship_Methods/page\\.mdx": {
frontmatterData: {
slug: "/references/data-model/relationship-methods",
},
reflectionDescription:
"The following methods are used to define a relationship between two data models.",
reflectionTitle: {
suffix: "- API Reference",
},
},
"^dml/Relationship_Methods": {
frontmatterData: {
slug: "/references/data-model/relationship-methods/{{alias-lower}}",
sidebar_label: "{{alias}}",
},
reflectionTitle: {
suffix: "Relationship Method - API Reference",
},
},
"^dml/.*Model_Methods/page\\.mdx": {
frontmatterData: {
slug: "/references/data-model/model-methods",
},
reflectionDescription:
"The following methods are used on a module to configure it.",
reflectionTitle: {
suffix: "- API Reference",
},
},
"^dml/Model_Methods": {
frontmatterData: {
slug: "/references/data-model/model-methods/{{alias-lower}}",
sidebar_label: "{{alias}}",
},
reflectionTitle: {
suffix: "Method - API Reference",
},
},
"^dml/.*Property_Configuration_Methods/page\\.mdx": {
frontmatterData: {
slug: "/references/data-model/property-configuration",
},
reflectionDescription:
"The following methods are used on a property to configure it.",
reflectionTitle: {
suffix: "- API Reference",
},
},
"^dml/Property_Configuration_Methods": {
frontmatterData: {
slug: "/references/data-model/property-configuration/{{alias-lower}}",
sidebar_label: "{{alias}}",
},
reflectionTitle: {
suffix: "Method - API Reference",
},
},
"^dml/.*/types/.*": {
sections: {
...baseSectionsOptions,
member_getterSetter: false,
member_returns: false,
member_declaration_children: true,
},
},
}
export default dmlOptions
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/index.ts
+2
View File
@@ -11,9 +11,11 @@ import paymentProviderOptions from "./payment-provider.js"
import searchOptions from "./search.js"
import taxProviderOptions from "./tax-provider.js"
import workflowsOptions from "./workflows.js"
import dmlOptions from "./dml.js"
const mergerCustomOptions: FormattingOptionsType = {
...authProviderOptions,
...dmlOptions,
...fileOptions,
...fulfillmentProviderOptions,
...jsClientOptions,
www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts
+1 -1
View File
@@ -28,7 +28,7 @@ const mergerOptions: Partial<TypeDocOptions> = {
objectLiteralTypeDeclarationStyle: "component",
mdxOutput: true,
maxLevel: 3,
allReflectionsHaveOwnDocument: [...modules, "workflows"],
allReflectionsHaveOwnDocument: [...modules, "dml", "workflows"],
allReflectionsHaveOwnDocumentInNamespace: ["Utilities"],
formatting: {
"*": {
www/utils/packages/typedoc-generate-references/src/constants/references.ts
+1
View File
@@ -22,6 +22,7 @@ export const modules = [
const allReferences = [
...modules,
"auth-provider",
"dml",
"file",
"fulfillment-provider",
"medusa-config",
www/utils/packages/typedoc-plugin-custom/src/generate-namespace.ts
+29 -10
View File
@@ -7,6 +7,7 @@ import {
Converter,
DeclarationReflection,
ParameterType,
Reflection,
ReflectionCategory,
ReflectionKind,
} from "typedoc"
@@ -31,7 +32,7 @@ export class GenerateNamespacePlugin {
this.declareOptions()
this.app.converter.on(
Converter.EVENT_CREATE_DECLARATION,
Converter.EVENT_RESOLVE,
this.handleCreateDeclarationEvent.bind(this)
)
this.app.converter.on(
@@ -145,14 +146,17 @@ export class GenerateNamespacePlugin {
* create categories in the last namespace if the
* reflection has a category
*/
attachCategories(reflection: DeclarationReflection) {
attachCategories(
reflection: DeclarationReflection,
comments: Comment | undefined
) {
if (!this.currentNamespaceHeirarchy.length) {
return
}
const parentNamespace =
this.currentNamespaceHeirarchy[this.currentNamespaceHeirarchy.length - 1]
reflection.comment?.blockTags
comments?.blockTags
.filter((tag) => tag.tag === "@category")
.forEach((tag) => {
const categoryName = tag.content[0].text
@@ -170,10 +174,10 @@ export class GenerateNamespacePlugin {
})
}
handleCreateDeclarationEvent(
context: Context,
reflection: DeclarationReflection
) {
handleCreateDeclarationEvent(context: Context, reflection: Reflection) {
if (!(reflection instanceof DeclarationReflection)) {
return
}
this.readOptions()
if (this.options?.parentNamespace && !this.parentNamespace) {
this.parentNamespace =
@@ -185,7 +189,8 @@ export class GenerateNamespacePlugin {
this.currentNamespaceHeirarchy.push(this.parentNamespace)
}
this.currentContext = context
reflection.comment?.blockTags
const comments = this.getReflectionComments(reflection)
comments?.blockTags
.filter((tag) => tag.tag === "@customNamespace")
.forEach((tag) => {
this.generateNamespaceFromTag({
@@ -202,8 +207,8 @@ export class GenerateNamespacePlugin {
this.currentContext?.addChild(reflection)
})
reflection.comment?.removeTags("@customNamespace")
this.attachCategories(reflection)
comments?.removeTags("@customNamespace")
this.attachCategories(reflection, comments)
this.currentContext = undefined
this.currentNamespaceHeirarchy = []
}
@@ -251,6 +256,20 @@ export class GenerateNamespacePlugin {
this.scannedComments = true
}
getReflectionComments(
reflection: DeclarationReflection
): Comment | undefined {
if (reflection.comment) {
return reflection.comment
}
// try to retrieve comment from signature
if (!reflection.signatures?.length) {
return
}
return reflection.signatures.find((signature) => signature.comment)?.comment
}
// for debugging
printCurrentHeirarchy() {
return this.currentNamespaceHeirarchy.map((heirarchy) => heirarchy.name)
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-show-returns.ts
+4 -1
View File
@@ -9,7 +9,10 @@ export default function (theme: MarkdownTheme) {
function (this: SignatureReflection, options: Handlebars.HelperOptions) {
this.parent =
getCorrectDeclarationReflection(this.parent, theme) || this.parent
return this.type && !this.parent?.kindOf(ReflectionKind.Constructor)
const { sections } = theme.getFormattingOptionsForLocation()
return sections?.member_returns !== false &&
this.type &&
!this.parent?.kindOf(ReflectionKind.Constructor)
? options.fn(this)
: options.inverse(this)
}
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/parameter-component.ts
+12 -6
View File
@@ -17,13 +17,19 @@ export default function (theme: MarkdownTheme) {
const parameters = this.reduce(
(acc: ReflectionParameterType[], current) => parseParams(current, acc),
[]
).map((parameter) =>
reflectionComponentFormatter({
reflection: parameter,
level: 1,
maxLevel,
})
)
.filter((parameter) => {
// remove parameters that are supposed to be nested
return !parameter.name.includes(".")
})
.map((parameter) =>
reflectionComponentFormatter({
reflection: parameter,
level: 1,
maxLevel,
project: theme.project,
})
)
return formatParameterComponent({
parameterComponent,
www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/toc.ts
+4 -1
View File
@@ -14,6 +14,7 @@ export default function (theme: MarkdownTheme) {
const md: string[] = []
const { hideInPageTOC } = theme
const { hideTocHeaders } = theme.getFormattingOptionsForLocation()
const isVisible = this.groups?.some((group) =>
group.allChildrenHaveOwnDocument()
@@ -44,7 +45,9 @@ export default function (theme: MarkdownTheme) {
})
} else {
if (!hideInPageTOC || group.allChildrenHaveOwnDocument()) {
md.push(`${headingLevel} ${groupTitle}\n\n`)
if (!hideTocHeaders) {
md.push(`${headingLevel} ${groupTitle}\n\n`)
}
pushGroup(group, md)
md.push("\n")
}
www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts
+1 -1
View File
@@ -162,7 +162,7 @@ export function reflectionComponentFormatter({
: getTypeChildren({
reflectionType: reflection.type!,
project: project || reflection.project,
maxLevel,
maxLevel: maxLevel || MarkdownTheme.MAX_LEVEL,
})
children
www/utils/packages/types/lib/index.d.ts
Vendored
+2
View File
@@ -29,6 +29,7 @@ export type SectionKey =
| "member_sources_definedIn"
| "members_group_categories"
| "members_categories"
| "member_returns"
| "title_reflectionPath"
| "reflection_comment"
| "reflection_typeParameters"
@@ -78,6 +79,7 @@ export type FormattingOptionType = {
startSections?: string[]
endSections?: string[]
shouldIncrementAfterStartSections?: boolean
hideTocHeaders?: boolean
}
export declare module "typedoc" {
www/utils/packages/utils/src/get-type-children.ts
+14 -1
View File
@@ -34,6 +34,19 @@ export function getTypeChildren({
)
})
break
case "union":
reflectionType.types.forEach((childItem) => {
// TODO this should ensure that the items are unique.
children.push(
...getTypeChildren({
reflectionType: childItem,
project,
level: level + 1,
maxLevel,
})
)
})
break
case "reference":
// eslint-disable-next-line no-case-declarations
const referencedReflection = reflectionType.reflection
@@ -53,7 +66,7 @@ export function getTypeChildren({
children = getTypeChildren({
reflectionType: referencedReflection.type,
project,
level: level + 1,
level,
maxLevel,
})
}