From fde1e23995eaed19116bb97785c502fa37b207f5 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 14 Dec 2023 18:25:40 +0200 Subject: [PATCH] chore: refactored docs-util (#5876) --- docs-util/.eslintrc.js | 9 +- .../packages/typedoc-config/js-client.js | 4 - .../packages/typedoc-config/package.json | 3 + .../typedoc-config/utils/get-config.js | 2 +- .../typedoc-plugin-custom/src/api-ignore.ts | 3 +- .../src/resolve-references-plugin.ts | 6 - .../src/types/index.d.ts | 6 - .../typedoc-plugin-custom/tsconfig.json | 3 +- .../package.json | 1 + .../helpers/has-more-than-one-signature.ts | 2 +- .../src/resources/helpers/section-enabled.ts | 2 +- .../src/theme.ts | 13 +- .../src/types.ts | 130 ------------- .../src/utils/reflection-formatter.ts | 1 + docs-util/packages/types/lib/index.d.ts | 182 ++++++++++++++++++ docs-util/packages/types/lib/index.js | 2 + docs-util/packages/types/package.json | 22 +++ docs-util/packages/types/tsconfig.json | 7 + docs-util/packages/utils/src/get-type-str.ts | 4 + docs-util/tsconfig.json | 3 +- docs-util/yarn.lock | 12 ++ 21 files changed, 255 insertions(+), 162 deletions(-) delete mode 100644 docs-util/packages/typedoc-plugin-custom/src/types/index.d.ts create mode 100644 docs-util/packages/types/lib/index.d.ts create mode 100644 docs-util/packages/types/lib/index.js create mode 100644 docs-util/packages/types/package.json create mode 100644 docs-util/packages/types/tsconfig.json diff --git a/docs-util/.eslintrc.js b/docs-util/.eslintrc.js index 4930121c51..00efa299e4 100644 --- a/docs-util/.eslintrc.js +++ b/docs-util/.eslintrc.js @@ -92,11 +92,14 @@ module.exports = { parserOptions: { project: [ "./tsconfig.json", + "./packages/react-docs-generator/tsconfig.json", "./packages/scripts/tsconfig.json", "./packages/typedoc-config/tsconfig.json", - "./packages/typedoc-frontmatter-plugin/tsconfig.json", - "./packages/typedoc-modules-plugin/tsconfig.json", - "./packages/typedoc-markdown-medusa-plugin/tsconfig.json" + "./packages/typedoc-plugin-custom/tsconfig.json", + "./packages/typedoc-markdown-medusa-plugin/tsconfig.json", + "./packages/types/tsconfig.json", + "./packages/utils/tsconfig.json", + "./packages/workflows-diagrams-generator/tsconfig.json" ] }, rules: { diff --git a/docs-util/packages/typedoc-config/js-client.js b/docs-util/packages/typedoc-config/js-client.js index ff228a17b2..d8b4eb30dd 100644 --- a/docs-util/packages/typedoc-config/js-client.js +++ b/docs-util/packages/typedoc-config/js-client.js @@ -14,9 +14,5 @@ module.exports = getConfig({ ...globalTypedocOptions.exclude, path.join(pathPrefix, "packages/medusa-js/src/resources/base.ts"), ], - // internalModule: "internal", ignoreApi: true, - // outputModules: false, - // outputNamespace: false, - // excludeReferences: true, }) diff --git a/docs-util/packages/typedoc-config/package.json b/docs-util/packages/typedoc-config/package.json index 6229a26698..048d3a872d 100644 --- a/docs-util/packages/typedoc-config/package.json +++ b/docs-util/packages/typedoc-config/package.json @@ -12,5 +12,8 @@ "version": "0.0.0", "dependencies": { "glob": "^10.3.10" + }, + "devDependencies": { + "types": "*" } } diff --git a/docs-util/packages/typedoc-config/utils/get-config.js b/docs-util/packages/typedoc-config/utils/get-config.js index 0e6d600e58..2a78621c84 100644 --- a/docs-util/packages/typedoc-config/utils/get-config.js +++ b/docs-util/packages/typedoc-config/utils/get-config.js @@ -14,7 +14,7 @@ function getEntryPoints(entryPointPaths) { /** * - * @param {Record} param0 - The configuration options + * @param {Partial} param0 - The configuration options * @returns {import('typedoc').TypeDocOptions} */ function getConfig({ diff --git a/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts b/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts index a4075b1d06..989b2c8253 100644 --- a/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts +++ b/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts @@ -15,11 +15,12 @@ export function load(app: Application) { }) app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => { + const isIgnoreApiEnabled = app.options.getValue("ignoreApi") for (const reflection of context.project.getReflectionsByKind( ReflectionKind.All )) { if (reflection.comment?.hasModifier("@apiIgnore")) { - if (app.options.getValue("ignoreApi")) { + if (isIgnoreApiEnabled) { context.project.removeReflection(reflection) } else { reflection.comment.removeModifier(`@apiIgnore`) diff --git a/docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts b/docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts index c5eb0a2b76..65857c0f56 100644 --- a/docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts +++ b/docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts @@ -12,12 +12,6 @@ import { ParameterType, } from "typedoc" -declare module "typedoc" { - export interface TypeDocOptionMap { - internalModule: string - } -} - let hasMonkeyPatched = false export function load(app: Application) { diff --git a/docs-util/packages/typedoc-plugin-custom/src/types/index.d.ts b/docs-util/packages/typedoc-plugin-custom/src/types/index.d.ts deleted file mode 100644 index 4a4105c1c6..0000000000 --- a/docs-util/packages/typedoc-plugin-custom/src/types/index.d.ts +++ /dev/null @@ -1,6 +0,0 @@ -export declare module "typedoc" { - declare interface TypeDocOptionMap { - enableInternalResolve: boolean - internalModule: string - } -} diff --git a/docs-util/packages/typedoc-plugin-custom/tsconfig.json b/docs-util/packages/typedoc-plugin-custom/tsconfig.json index d9c48aada9..b3b4792cd9 100644 --- a/docs-util/packages/typedoc-plugin-custom/tsconfig.json +++ b/docs-util/packages/typedoc-plugin-custom/tsconfig.json @@ -4,6 +4,5 @@ "outDir": "./dist", "rootDir": "./src" }, - "include": ["src", "src/types"], - "typeRoots": ["./src/types/index.d.ts"] + "include": ["src"] } \ No newline at end of file diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/package.json b/docs-util/packages/typedoc-plugin-markdown-medusa/package.json index 87ec7551d0..3aba836f3b 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/package.json +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/package.json @@ -23,6 +23,7 @@ "devDependencies": { "@types/node": "^16.11.10", "copyfiles": "^2.4.1", + "types": "*", "typescript": "5.2" }, "keywords": [ diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts index 0a1a9fd621..d24549f3d8 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts @@ -5,7 +5,7 @@ export default function () { Handlebars.registerHelper( "hasMoreThanOneSignature", function (model: DeclarationReflection) { - return (model.signatures?.length || 0) > 1 + return (model?.signatures?.length || 0) > 1 } ) } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/section-enabled.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/section-enabled.ts index e94a1c5119..51b8bf127e 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/section-enabled.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/section-enabled.ts @@ -1,6 +1,6 @@ +import { SectionKey } from "types" import { MarkdownTheme } from "../../theme" import * as Handlebars from "handlebars" -import { SectionKey } from "../../types" export default function (theme: MarkdownTheme) { Handlebars.registerHelper( diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts index 74cb684cb8..9f0c04d63a 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts @@ -20,12 +20,13 @@ import { registerPartials, } from "./render-utils" import { formatContents } from "./utils" -import { + +import type { FormattingOptionType, FormattingOptionsType, - Mapping, - ObjectLiteralDeclarationStyle, -} from "./types" + ParameterStyle, +} from "types" +import { Mapping } from "./types" export class MarkdownTheme extends Theme { allReflectionsHaveOwnDocument!: string[] @@ -44,7 +45,7 @@ export class MarkdownTheme extends Theme { out!: string publicPath!: string preserveAnchorCasing!: boolean - objectLiteralTypeDeclarationStyle: ObjectLiteralDeclarationStyle + objectLiteralTypeDeclarationStyle: ParameterStyle formattingOptions: FormattingOptionsType mdxOutput: boolean outputNamespace: boolean @@ -84,7 +85,7 @@ export class MarkdownTheme extends Theme { ) as boolean this.objectLiteralTypeDeclarationStyle = this.getOption( "objectLiteralTypeDeclarationStyle" - ) as ObjectLiteralDeclarationStyle + ) as ParameterStyle this.formattingOptions = this.getOption( "formatting" ) as FormattingOptionsType diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts index 8c43b1ddb4..69e8c07d57 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts @@ -3,88 +3,12 @@ import { DeclarationReflection, PageEvent, ParameterReflection, - Reflection, ReflectionKind, TypeParameterReflection, } from "typedoc" export type ParameterStyle = "table" | "list" | "component" -export type ReflectionTitleOptions = { - typeParameters?: boolean - kind?: boolean -} - -export type ObjectLiteralDeclarationStyle = "table" | "list" | "component" - -export type SectionKey = - | "comment" - | "member_declaration" - | "member_declaration_title" - | "member_declaration_comment" - | "member_declaration_typeParameters" - | "member_declaration_indexSignature" - | "member_declaration_signatures" - | "member_declaration_typeDeclaration" - | "member_declaration_example" - | "member_getteSetter_getSignature" - | "member_getteSetter_setSignature" - | "member_signatures" - | "member_getterSetter" - | "member_reference" - | "member_signature_title" - | "member_signature_comment" - | "member_signature_typeParameters" - | "member_signature_parameters" - | "member_signature_example" - | "member_signature_returns" - | "member_signature_declarationSignatures" - | "member_signature_declarationChildren" - | "member_signature_sources" - | "member_sources_implementationOf" - | "member_sources_inheritedFrom" - | "member_sources_overrides" - | "member_sources_definedIn" - | "members_group_categories" - | "members_categories" - | "title_reflectionPath" - | "reflection_comment" - | "reflection_typeParameters" - | "reflection_hierarchy" - | "reflection_implements" - | "reflection_implementedBy" - | "reflection_callable" - | "reflection_indexable" - -export type FormattingOptionType = { - sections?: { - [k in SectionKey]: boolean - } - reflectionGroups?: { - [k: string]: boolean - } - reflectionTitle?: { - kind: boolean - typeParameters: boolean - suffix?: string - fullReplacement?: string - } - reflectionDescription?: string - expandMembers?: boolean - showCommentsAsHeader?: boolean - showCommentsAsDetails?: boolean - parameterStyle?: ParameterStyle - frontmatterData?: Record - parameterComponent?: string - parameterComponentExtraProps?: Record - mdxImports?: string[] - maxLevel?: number -} - -export type FormattingOptionsType = { - [k: string]: FormattingOptionType -} - export type ReflectionParameterType = | ParameterReflection | DeclarationReflection @@ -107,57 +31,3 @@ export type Parameter = { expandable: boolean children?: Parameter[] } - -export class NavigationItem { - title: string - url: string - dedicatedUrls?: string[] - parent?: NavigationItem - children?: NavigationItem[] - isLabel?: boolean - isVisible?: boolean - isCurrent?: boolean - isModules?: boolean - isInPath?: boolean - reflection?: Reflection - - constructor( - title?: string, - url?: string, - parent?: NavigationItem, - reflection?: Reflection - ) { - this.title = title || "" - this.url = url || "" - this.parent = parent - this.reflection = reflection - - if (!url) { - this.isLabel = true - } - - if (this.parent) { - if (!this.parent.children) { - this.parent.children = [] - } - this.parent.children.push(this) - } - } - - static create( - reflection: Reflection, - parent?: NavigationItem, - useShortNames?: boolean - ) { - let name: string - if (useShortNames || (parent && parent.parent)) { - name = reflection.name - } else { - name = reflection.getFullName() - } - - name = name.trim() - - return new NavigationItem(name, reflection.url, parent, reflection) - } -} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts index 18f6259394..668cd24591 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts @@ -217,6 +217,7 @@ export function reflectionTableFormatter({ reflectionType: parameter, collapse: "object", wrapBackticks: true, + getRelativeUrlMethod: Handlebars.helpers.relativeURL, }) ) diff --git a/docs-util/packages/types/lib/index.d.ts b/docs-util/packages/types/lib/index.d.ts new file mode 100644 index 0000000000..d7acc4eb39 --- /dev/null +++ b/docs-util/packages/types/lib/index.d.ts @@ -0,0 +1,182 @@ +export type SectionKey = + | "comment" + | "member_declaration" + | "member_declaration_title" + | "member_declaration_comment" + | "member_declaration_typeParameters" + | "member_declaration_indexSignature" + | "member_declaration_signatures" + | "member_declaration_typeDeclaration" + | "member_declaration_example" + | "member_getteSetter_getSignature" + | "member_getteSetter_setSignature" + | "member_signatures" + | "member_getterSetter" + | "member_reference" + | "member_signature_title" + | "member_signature_comment" + | "member_signature_typeParameters" + | "member_signature_parameters" + | "member_signature_example" + | "member_signature_returns" + | "member_signature_declarationSignatures" + | "member_signature_declarationChildren" + | "member_signature_sources" + | "member_sources_implementationOf" + | "member_sources_inheritedFrom" + | "member_sources_overrides" + | "member_sources_definedIn" + | "members_group_categories" + | "members_categories" + | "title_reflectionPath" + | "reflection_comment" + | "reflection_typeParameters" + | "reflection_hierarchy" + | "reflection_implements" + | "reflection_implementedBy" + | "reflection_callable" + | "reflection_indexable" + +export type ParameterStyle = "table" | "list" | "component" + +export type FormattingOptionsType = { + [k: string]: FormattingOptionType +} + +export type FormattingOptionType = { + sections?: { + [k in SectionKey]: boolean + } + reflectionGroups?: { + [k: string]: boolean + } + reflectionTitle?: { + kind: boolean + typeParameters: boolean + suffix?: string + fullReplacement?: string + } + reflectionDescription?: string + expandMembers?: boolean + showCommentsAsHeader?: boolean + showCommentsAsDetails?: boolean + parameterStyle?: ParameterStyle + frontmatterData?: Record + parameterComponent?: string + parameterComponentExtraProps?: Record + mdxImports?: string[] + maxLevel?: number +} + +export declare module "typedoc" { + declare interface TypeDocOptionMap { + /** + * Enable resolving internal types. + * @defaultValue false + */ + enableInternalResolve: boolean + /** + * The name of the internal module. Requires enabling `enableInternalResolve`. + * @defaultValue "internal" + */ + internalModule: string + /** + * Whether to remove reflections having the `@apiIgnore` tag. + * @defaultValue false + */ + ignoreApi: boolean + /** + * The path to the ESLint configurations to apply. + */ + eslintPathName: string + /** + * The path to resolve plugins used in the ESLint configurations. + */ + pluginsResolvePath: string + /** + * An object of key-value pairs to be added to frontmatter + */ + frontmatterData: Record + /** + * [Markdown Plugin] Do not render page title. + * @defaultValue false + */ + hidePageTitle: boolean + /** + * [Markdown Plugin] Do not render breadcrumbs in template. + * @defaultValue false + */ + hideBreadcrumbs: boolean + /** + * [Markdown Plugin] Specifies the base path that all links to be served from. If omitted all urls will be relative. + */ + publicPath: string + /** + * [Markdown Plugin] Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids. Should be set for Bitbucket Server docs. + * @defaultValue false + */ + namedAnchors: boolean + /** + * [Markdown Plugin] Specify module names where all reflections are outputted into seperate files. + */ + allReflectionsHaveOwnDocument: string[] + /** + * [Markdown Plugin] Separator used to format filenames. + * @defaultValue "." + */ + filenameSeparator: string + /** + * [Markdown Plugin] The file name of the entry document. + * @defaultValue "README.md" + */ + entryDocument: string + /** + * [Markdown Plugin] Do not render in-page table of contents items. + * @defaultValue false + */ + hideInPageTOC: boolean + /** + * [Markdown Plugin] Customise the index page title. + */ + indexTitle: string + /** + * [Markdown Plugin] Do not add special symbols for class members. + * @defaultValue true + */ + hideMembersSymbol: boolean + /** + * [Markdown Plugin] Preserve anchor casing when generating links. + * @defaultValue false + */ + preserveAnchorCasing: boolean + /** + * [Markdown Plugin] Specify the Type Declaration Render Style + * @defaultValue table + */ + objectLiteralTypeDeclarationStyle: ParameterStyle + /** + * [Markdown Plugin] Formatting options that can be specified either on a specific document or to all documents + */ + formatting: FormattingOptionType + /** + * [Markdown Plugin] Whether outputted files should have an mdx extension. + * @defaultValue false + */ + mdxOutput: boolean + /** + * [Markdown Plugin] The maximum level to expand when retrieving reflection types. + * @defaultValue 3 + */ + maxLevel: number + /** + * [Markdown Plugin] Whether to output modules file for namespaces. + * @defaultValue true + */ + outputNamespace: boolean + /** + * [Markdown Plugin] Whether to output module files. + * @defaultValue true + */ + outputModules: boolean + } +} diff --git a/docs-util/packages/types/lib/index.js b/docs-util/packages/types/lib/index.js new file mode 100644 index 0000000000..333541a3a4 --- /dev/null +++ b/docs-util/packages/types/lib/index.js @@ -0,0 +1,2 @@ +// noop +module.exports = {} diff --git a/docs-util/packages/types/package.json b/docs-util/packages/types/package.json new file mode 100644 index 0000000000..2f2cc6eb40 --- /dev/null +++ b/docs-util/packages/types/package.json @@ -0,0 +1,22 @@ +{ + "name": "types", + "private": true, + "license": "MIT", + "publishConfig": { + "access": "public" + }, + "scripts": { + "build": "tsc", + "watch": "tsc --watch", + "lint": "eslint --ext .ts src" + }, + "peerDependencies": { + "typedoc": "0.25.x" + }, + "devDependencies": { + "typescript": "5.2" + }, + "version": "0.0.0", + "main": "./lib/index.js", + "types": "./lib/index.d.ts" +} diff --git a/docs-util/packages/types/tsconfig.json b/docs-util/packages/types/tsconfig.json new file mode 100644 index 0000000000..db235fff10 --- /dev/null +++ b/docs-util/packages/types/tsconfig.json @@ -0,0 +1,7 @@ +{ + "extends": "../../tsconfig", + "compilerOptions": { + "rootDir": "lib", + }, + "include": ["lib/index.d.ts"] +} \ No newline at end of file diff --git a/docs-util/packages/utils/src/get-type-str.ts b/docs-util/packages/utils/src/get-type-str.ts index 5d9daabceb..20ff610118 100644 --- a/docs-util/packages/utils/src/get-type-str.ts +++ b/docs-util/packages/utils/src/get-type-str.ts @@ -154,6 +154,7 @@ export function getReflectionType({ collapse, wrapBackticks = true, hideLink = false, + ...options }: TypeOptions): string { if ("signatures" in model && model.signatures) { return collapse === "function" || collapse === "all" @@ -163,6 +164,7 @@ export function getReflectionType({ wrapBackticks, hideLink, escape: !wrapBackticks, + ...options, }) } return collapse === "object" || collapse === "all" @@ -172,6 +174,7 @@ export function getReflectionType({ wrapBackticks, hideLink, escape: !wrapBackticks, + ...options, })}${wrapBackticks ? "`" : ""}` } @@ -347,6 +350,7 @@ export function getReferenceType({ wrapBackticks: false, hideLink, escape: false, + getRelativeUrlMethod, ...options, }) ) diff --git a/docs-util/tsconfig.json b/docs-util/tsconfig.json index f5a61fc9f7..a154984911 100644 --- a/docs-util/tsconfig.json +++ b/docs-util/tsconfig.json @@ -10,7 +10,8 @@ "sourceMap": true, "skipLibCheck": true, "rootDir": ".", - "allowJs": true + "allowJs": true, + "typeRoots": ["node_modules/@types", "./packages/types"] }, "include": ["**/*.ts", "**/*.js"], "exclude": ["**/node_modules/**", "dist"] diff --git a/docs-util/yarn.lock b/docs-util/yarn.lock index d6d5d38322..e22539bbf5 100644 --- a/docs-util/yarn.lock +++ b/docs-util/yarn.lock @@ -4417,6 +4417,7 @@ __metadata: resolution: "typedoc-config@workspace:packages/typedoc-config" dependencies: glob: ^10.3.10 + types: "*" peerDependencies: typedoc: 0.25.x languageName: unknown @@ -4463,6 +4464,7 @@ __metadata: "@types/node": ^16.11.10 copyfiles: ^2.4.1 handlebars: ^4.7.8 + types: "*" typescript: 5.2 utils: "*" peerDependencies: @@ -4544,6 +4546,16 @@ __metadata: languageName: node linkType: hard +"types@*, types@workspace:packages/types": + version: 0.0.0-use.local + resolution: "types@workspace:packages/types" + dependencies: + typescript: 5.2 + peerDependencies: + typedoc: 0.25.x + languageName: unknown + linkType: soft + "typescript@npm:5.2": version: 5.2.2 resolution: "typescript@npm:5.2.2"