chore: refactored docs-util (#5876)

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-plugin-custom/tsconfig.json",
-          "./packages/typedoc-modules-plugin/tsconfig.json",
+          "./packages/typedoc-markdown-medusa-plugin/tsconfig.json",
-          "./packages/typedoc-markdown-medusa-plugin/tsconfig.json"
+          "./packages/types/tsconfig.json",
+          "./packages/utils/tsconfig.json",
+          "./packages/workflows-diagrams-generator/tsconfig.json"
         ]
       },
       rules: {

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,
 })

docs-util/packages/typedoc-config/package.json

@@ -12,5 +12,8 @@
   "version": "0.0.0",
   "dependencies": {
     "glob": "^10.3.10"
+  },
+  "devDependencies": {
+    "types": "*"
   }
 }

docs-util/packages/typedoc-config/utils/get-config.js

@@ -14,7 +14,7 @@ function getEntryPoints(entryPointPaths) {
 
 /**
  *
- * @param {Record<string, any>} param0 - The configuration options
+ * @param {Partial<import('typedoc').TypeDocOptions>} param0 - The configuration options
  * @returns {import('typedoc').TypeDocOptions}
  */
 function getConfig({

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`)

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) {

docs-util/packages/typedoc-plugin-custom/src/types/index.d.ts

@@ -1,6 +0,0 @@
-export declare module "typedoc" {
-  declare interface TypeDocOptionMap {
-    enableInternalResolve: boolean
-    internalModule: string
-  }
-}

docs-util/packages/typedoc-plugin-custom/tsconfig.json

@@ -4,6 +4,5 @@
     "outDir": "./dist",
     "rootDir": "./src"
   },
-  "include": ["src", "src/types"],
+  "include": ["src"]
-  "typeRoots": ["./src/types/index.d.ts"]
 }

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": [

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
     }
   )
 }

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(

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,
+  ParameterStyle,
-  ObjectLiteralDeclarationStyle,
+} from "types"
-} 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

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<string, unknown>
-  parameterComponent?: string
-  parameterComponentExtraProps?: Record<string, unknown>
-  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)
-  }
-}

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,
         })
   )
 

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<string, unknown>
+  parameterComponent?: string
+  parameterComponentExtraProps?: Record<string, unknown>
+  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<string, unknown>
+    /**
+     * [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
+  }
+}

docs-util/packages/types/lib/index.js

@@ -0,0 +1,2 @@
+// noop
+module.exports = {}

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"
+}

docs-util/packages/types/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig",
+  "compilerOptions": {
+    "rootDir": "lib",
+  },
+  "include": ["lib/index.d.ts"]
+}

docs-util/packages/utils/src/get-type-str.ts

@@ -154,6 +154,7 @@ export function getReflectionType({
   collapse,
   wrapBackticks = true,
   hideLink = false,
+  ...options
 }: TypeOptions<ReflectionParameterType>): 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,
             })
           )

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"]

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"