docs: TSDoc + reference of fulfillment service (#5761)

docs-util/packages/scripts/package.json

@@ -33,7 +33,7 @@
     "typedoc-plugin-missing-exports": "^2.1.0",
     "typedoc-plugin-reference-excluder": "1.1.3",
     "typedoc-plugin-rename-defaults": "^0.6.6",
-    "typescript": "^5.2.2"
+    "typescript": "5.2"
   },
   "devDependencies": {
     "@types/randomcolor": "^0.5.8"

docs-util/packages/typedoc-config/fulfillment.js

@@ -0,0 +1,64 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const path = require("path")
+const globalTypedocOptions = require("./_base")
+
+const pathPrefix = path.join(__dirname, "..", "..", "..")
+
+module.exports = {
+  ...globalTypedocOptions,
+  entryPoints: [
+    path.join(
+      pathPrefix,
+      "packages/medusa/src/interfaces/fulfillment-service.ts"
+    ),
+  ],
+  out: [path.join(pathPrefix, "www/apps/docs/content/references/fulfillment")],
+  tsconfig: path.join(__dirname, "extended-tsconfig", "medusa.json"),
+  name: "Fulfillment Provider Reference",
+  indexTitle: "Fulfillment Provider Reference",
+  entryDocument: "_index.mdx",
+  hideInPageTOC: true,
+  hideBreadcrumbs: true,
+  formatting: {
+    "*": {
+      showCommentsAsHeader: true,
+      sections: {
+        member_sources_definedIn: false,
+        reflection_hierarchy: false,
+        member_sources_inheritedFrom: false,
+        member_sources_implementationOf: false,
+        reflection_implementedBy: false,
+        member_signature_sources: false,
+        reflection_callable: false,
+        reflection_indexable: false,
+        reflection_implements: false,
+        member_signature_title: false,
+        member_signature_returns: false,
+      },
+      parameterStyle: "component",
+      parameterComponent: "ParameterTypes",
+      mdxImports: [
+        `import ParameterTypes from "@site/src/components/ParameterTypes"`,
+      ],
+      reflectionGroups: {
+        Properties: false,
+      },
+      frontmatterData: {
+        displayed_sidebar: "modules",
+      },
+    },
+    AbstractFulfillmentService: {
+      reflectionDescription: `In this document, you’ll learn how to create a fulfillment provider to a Medusa backend and the methods you must implement in it. If you’re unfamiliar with the Shipping architecture in Medusa, make sure to [check out the overview first](https://docs.medusajs.com/modules/carts-and-checkout/shipping).`,
+      frontmatterData: {
+        displayed_sidebar: "modules",
+        slug: "/modules/carts-and-checkout/backend/add-fulfillment-provider",
+      },
+      reflectionTitle: {
+        fullReplacement: "How to Create a Fulfillment Provider",
+      },
+    },
+  },
+  objectLiteralTypeDeclarationStyle: "component",
+  mdxOutput: true,
+  maxLevel: 2,
+}

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

@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@types/node": "^16.11.10",
-    "typescript": "^4.6"
+    "typescript": "5.2"
   },
   "keywords": [
     "typedocplugin",

docs-util/packages/typedoc-plugin-markdown-medusa/package.json

@@ -23,7 +23,7 @@
   "devDependencies": {
     "@types/node": "^16.11.10",
     "copyfiles": "^2.4.1",
-    "typescript": "^4.6"
+    "typescript": "5.2"
   },
   "keywords": [
     "typedocplugin",

docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -45,6 +45,10 @@ import commentTagHelper from "./resources/helpers/comment-tag"
 import exampleHelper from "./resources/helpers/example"
 import ifFeatureFlagHelper from "./resources/helpers/if-feature-flag"
 import featureFlagHelper from "./resources/helpers/feature-flag"
+import decrementCurrentTitleLevelHelper from "./resources/helpers/decrement-current-title-level"
+import incrementCurrentTitleLevelHelper from "./resources/helpers/increment-current-title-level"
+import hasMoreThanOneSignatureHelper from "./resources/helpers/has-more-than-one-signature"
+import ifCanShowConstructorsTitleHelper from "./resources/helpers/if-can-show-constructors-title"
 import { MarkdownTheme } from "./theme"
 
 // test
@@ -120,4 +124,8 @@ export function registerHelpers(theme: MarkdownTheme) {
   exampleHelper()
   ifFeatureFlagHelper()
   featureFlagHelper()
+  decrementCurrentTitleLevelHelper(theme)
+  incrementCurrentTitleLevelHelper(theme)
+  hasMoreThanOneSignatureHelper()
+  ifCanShowConstructorsTitleHelper()
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comment-tag.ts

@@ -6,7 +6,7 @@ import { MarkdownTheme } from "../../theme"
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "commentTag",
-    function (tag: CommentTag, commentLevel = 4, parent = null) {
+    function (tag: CommentTag, parent = null) {
       const { showCommentsAsHeader, showCommentsAsDetails } =
         theme.getFormattingOptionsForLocation()
       if (tag.tag === "@schema") {
@@ -19,8 +19,7 @@ export default function (theme: MarkdownTheme) {
 
       if (showCommentsAsHeader) {
         return `${Handlebars.helpers.titleLevel.call(
-          parent,
-          commentLevel
+          parent
         )} ${tagTitle}\n\n${tagContent}`
       } else if (showCommentsAsDetails) {
         return `<details>\n<summary>\n${tagTitle}\n</summary>\n\n${tagContent}\n\n</details>`

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts

@@ -10,7 +10,6 @@ export default function () {
       comment: Comment,
       showSummary = true,
       showTags = true,
-      commentLevel = 4,
       parent = null
     ) {
       const md: string[] = []
@@ -24,11 +23,7 @@ export default function () {
           (tag) => !EXCLUDED_TAGS.includes(tag.tag)
         )
         const tags = filteredTags.map((tag) => {
-          return Handlebars.helpers.commentTag(
-            tag,
-            commentLevel,
-            parent || comment
-          )
+          return Handlebars.helpers.commentTag(tag, parent || comment)
         })
         md.push(tags.join("\n\n"))
       }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/decrement-current-title-level.ts

@@ -0,0 +1,9 @@
+import { MarkdownTheme } from "../../theme"
+import * as Handlebars from "handlebars"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper("decrementCurrentTitleLevel", function () {
+    const { currentTitleLevel } = theme
+    theme.setCurrentTitleLevel(currentTitleLevel - 1)
+  })
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/example.ts

@@ -2,18 +2,15 @@ import * as Handlebars from "handlebars"
 import { Reflection } from "typedoc"
 
 export default function () {
-  Handlebars.registerHelper(
-    "example",
-    function (reflection: Reflection, commentLevel = 4) {
-      const exampleTag = reflection.comment?.blockTags.find(
-        (tag) => tag.tag === "@example"
-      )
+  Handlebars.registerHelper("example", function (reflection: Reflection) {
+    const exampleTag = reflection.comment?.blockTags.find(
+      (tag) => tag.tag === "@example"
+    )
 
-      if (!exampleTag) {
-        return ""
-      }
-
-      return Handlebars.helpers.commentTag(exampleTag, commentLevel, reflection)
+    if (!exampleTag) {
+      return ""
     }
-  )
+
+    return Handlebars.helpers.commentTag(exampleTag, reflection)
+  })
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts

@@ -0,0 +1,11 @@
+import { DeclarationReflection } from "typedoc"
+import * as Handlebars from "handlebars"
+
+export default function () {
+  Handlebars.registerHelper(
+    "hasMoreThanOneSignature",
+    function (model: DeclarationReflection) {
+      return (model.signatures?.length || 0) > 1
+    }
+  )
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-can-show-constructors-title.ts

@@ -0,0 +1,14 @@
+import * as Handlebars from "handlebars"
+import { ReflectionGroup } from "typedoc"
+
+export default function () {
+  Handlebars.registerHelper(
+    "ifCanShowConstructorTitle",
+    function (this: ReflectionGroup, options: Handlebars.HelperOptions) {
+      return this.title.toLowerCase() !== "constructors" ||
+        this.children.length > 1
+        ? options.fn(this)
+        : options.inverse(this)
+    }
+  )
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/increment-current-title-level.ts

@@ -0,0 +1,9 @@
+import { MarkdownTheme } from "../../theme"
+import * as Handlebars from "handlebars"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper("incrementCurrentTitleLevel", function () {
+    const { currentTitleLevel } = theme
+    theme.setCurrentTitleLevel(currentTitleLevel + 1)
+  })
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/reflection-title.ts

@@ -10,6 +10,10 @@ export default function (theme: MarkdownTheme) {
     function (this: PageEvent<any>, shouldEscape = true) {
       const { reflectionTitle } = theme.getFormattingOptionsForLocation()
 
+      if (reflectionTitle?.fullReplacement?.length) {
+        return reflectionTitle.fullReplacement
+      }
+
       const title: string[] = [""]
       if (
         reflectionTitle?.kind &&

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/signature-title.ts

@@ -13,11 +13,15 @@ export default function (theme: MarkdownTheme) {
     function (this: SignatureReflection, accessor?: string, standalone = true) {
       const { sections, expandMembers = false } =
         theme.getFormattingOptionsForLocation()
-      if (sections && sections.member_signature_title === false) {
+      const parentHasMoreThanOneSignature =
+        Handlebars.helpers.hasMoreThanOneSignature(this.parent)
+      if (
+        sections &&
+        sections.member_signature_title === false &&
+        !parentHasMoreThanOneSignature
+      ) {
         // only show title if there are more than one signatures
-        if (!this.parent.signatures || this.parent.signatures.length <= 1) {
-          return ""
-        }
+        return ""
       }
       const md: string[] = []
 
@@ -36,12 +40,12 @@ export default function (theme: MarkdownTheme) {
       if (accessor) {
         md.push(
           `${accessor}${
-            expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"
+            expandMembers ? `${Handlebars.helpers.titleLevel()} ` : "**"
           }${this.name}${!expandMembers ? "**" : ""}`
         )
       } else if (this.name !== "__call" && this.name !== "__type") {
         md.push(
-          `${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
+          `${expandMembers ? `${Handlebars.helpers.titleLevel()} ` : "**"}${
             this.name
           }${!expandMembers ? "**" : ""}`
         )

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/title-level.ts

@@ -1,44 +1,18 @@
 import { MarkdownTheme } from "../../theme"
 import * as Handlebars from "handlebars"
-import { SignatureReflection, Reflection } from "typedoc"
+import { Reflection } from "typedoc"
 
 export default function (theme: MarkdownTheme) {
-  Handlebars.registerHelper(
-    "titleLevel",
-    function (this: Reflection, originalLevel = 3): string {
-      const { expandMembers, sections } =
-        theme.getFormattingOptionsForLocation()
+  Handlebars.registerHelper("titleLevel", function (this: Reflection): string {
+    const { currentTitleLevel } = theme
 
-      if (!expandMembers) {
-        return Array(originalLevel).fill("#").join("")
-      }
+    // let titleLevel = currentTitleLevel
 
-      const { allReflectionsHaveOwnDocument } = theme
+    // if (isChild) {
+    //   titleLevel++
+    //   theme.setCurrentTitleLevel(titleLevel + 1)
+    // }
 
-      let isSignatureChild = false
-      if (
-        sections &&
-        sections.member_signature_title === false &&
-        (this instanceof SignatureReflection || this.variant === "signature")
-      ) {
-        // only show title if there are more than one signatures
-        isSignatureChild =
-          this.parent !== undefined &&
-          "signatures" in this.parent &&
-          (this.parent.signatures as SignatureReflection[]).length > 1
-      }
-
-      const numberToSubtract = allReflectionsHaveOwnDocument
-        ? isSignatureChild
-          ? 1
-          : 2
-        : isSignatureChild
-        ? 0
-        : 1
-
-      const level = originalLevel - numberToSubtract
-
-      return Array(level).fill("#").join("")
-    }
-  )
+    return Array(currentTitleLevel).fill("#").join("")
+  })
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/comment.hbs

@@ -4,7 +4,7 @@
 
 {{#if hasVisibleComponent}}
 
-{{{comments this true true 4 model}}}
+{{{comments this true true model}}}
 
 {{/if}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.declaration.hbs

@@ -12,15 +12,15 @@
 
 {{#if (sectionEnabled "member_declaration_example")}}
 
-{{{example this 4}}}
+{{{example this}}}
 
 {{/if}}
 
 {{#if (sectionEnabled "member_declaration_typeParameters")}}
 
 {{#if typeParameters}}
 
-{{{titleLevel 4}}} Type Parameters
+{{{titleLevel}}} Type Parameters
 
 {{#with typeParameters}}
 
@@ -40,7 +40,7 @@
 
 {{#with type.declaration.indexSignature}}
 
-{{titleLevel 4}} Index signature
+{{titleLevel}} Index signature
 
 {{{indexSignatureTitle}}}
 
@@ -58,17 +58,21 @@
 
 {{#if type.declaration.children}}
 
-{{{titleLevel 4}}} Call signature
+{{{titleLevel}}} Call signature
 
 {{else}}
 
-{{{titleLevel 4}}} Type declaration
+{{{titleLevel}}} Type declaration
 
 {{/if}}
 
 {{#each type.declaration.signatures}}
 
-{{> member.signature showSources=false commentLevel=5 }}
+{{incrementCurrentTitleLevel}}
+
+{{> member.signature showSources=false }}
+
+{{decrementCurrentTitleLevel}}
 
 {{/each}}
 
@@ -82,7 +86,7 @@
 
 {{#with type.declaration}}
 
-{{{titleLevel 4}}} Type declaration
+{{{titleLevel}}} Type declaration
 
 {{/with}}