docs: added file module docs (#7278)

www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts

@@ -16,8 +16,8 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
     name: "entities",
   }),
   file: getOptions({
-    entryPointPath: "packages/medusa/src/interfaces/file-service.ts",
-    tsConfigName: "medusa.json",
+    entryPointPath: "packages/core/utils/src/file/abstract-file-provider.ts",
+    tsConfigName: "utils.json",
     name: "file",
     parentIgnore: true,
   }),

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/file.ts

@@ -6,42 +6,89 @@ const fileOptions: FormattingOptionsType = {
       displayed_sidebar: "core",
     },
   },
-  "^file/.*AbstractFileService": {
+  "^file/.*AbstractFileProviderService": {
     reflectionGroups: {
       Properties: false,
     },
-    reflectionDescription: `In this document, you’ll learn how to create a file service in the Medusa backend and the methods you must implement in it.`,
+    reflectionDescription: `In this document, you’ll learn how to create a file provider module and the methods you must implement in it.`,
     frontmatterData: {
-      slug: "/references/file-service",
+      slug: "/references/file-provider-module",
     },
     reflectionTitle: {
-      fullReplacement: "How to Create a File Service",
+      fullReplacement: "How to Create a File Provider Module",
     },
+    shouldIncrementAfterStartSections: true,
+    expandMembers: true,
+    startSections: [
+      `## 1. Create Module Directory
+
+Start by creating a new directory for your module. For example, \`src/modules/my-file\`.`,
+      `## 2. Create the File Provider Service
+
+Create the file \`src/modules/my-file/service.ts\` that holds the implementation of the file service.
+
+The File Provider Module's main service must extend the \`AbstractFileProviderService\` class imported from \`@medusajs/utils\`:
+
+\`\`\`ts title="src/modules/my-file/service.ts"
+import { AbstractFileProviderService } from "@medusajs/utils"
+
+class MyFileProviderService extends AbstractFileProviderService {
+  // TODO implement methods
+}
+
+export default MyFileProviderService
+\`\`\``,
+    ],
     endSections: [
-      `## Test Implementation
+      `## 3. Create Module Definition File
 
-:::note
+Create the file \`src/modules/my-file/index.ts\` with the following content:
 
-If you created your file service in a plugin, refer to [this guide on how to test plugins](https://docs.medusajs.com/development/plugins/create#test-your-plugin).
+\`\`\`ts title="src/modules/my-file/index.ts"
+import MyFileProviderService from "./service"
 
-:::
-
-After finishing your file service implementation:
-
-1\\. Run the \`build\` command in the root of your Medusa backend:
-
-\`\`\`bash npm2yarn
-npm run build
+export default {
+  service: MyFileProviderService,
+}
 \`\`\`
 
-2\\. Start the backend with the \`develop\` command:
+This exports the module's definition, indicating that the \`MyFileProviderService\` is the main service of the module.`,
+      `## 4. Use Module
 
-\`\`\`bash
-npx medusa develop
+To use your File Provider Module, add it to the \`providers\` array of the File Module:
+
+<Note>
+
+The File Module accepts one provider only.
+
+</Note>
+
+\`\`\`js title="medusa-config.js"
+module.exports = {
+  // ...
+  modules: {
+    // ...
+    [Modules.FILE]: {
+      resolve: "@medusajs/file",
+      options: {
+        providers: [
+          {
+            resolve: "./dist/modules/my-file",
+            options: {
+              config: {
+                "my-file": {
+                  // provider options...
+                },
+              },
+            },
+          },
+        ],
+      },
+    },
+  },
+}
 \`\`\`
-
-3\\. Upload a file using the [Admin REST APIs](https://docs.medusajs.com/api/admin#uploads_postuploads) or using the Medusa admin, for example, to [upload a product's thumbnail](https://docs.medusajs.com/user-guide/products/manage#manage-thumbnails).
-    `,
+`,
     ],
   },
 }

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

@@ -63,6 +63,7 @@ import getDeclarationChildrenHelper from "./resources/helpers/get-declaration-ch
 import ifShowSeparatorForTitleLevelHelper from "./resources/helpers/if-show-separator-for-title-level"
 import shouldExpandPropertiesHelper from "./resources/helpers/should-expand-properties"
 import shouldExpandDeclarationChildrenHelper from "./resources/helpers/should-expand-declaration-children"
+import startSectionsHelper from "./resources/helpers/start-sections"
 import { MarkdownTheme } from "./theme"
 
 const TEMPLATE_PATH = path.join(__dirname, "resources", "templates")
@@ -154,4 +155,5 @@ export function registerHelpers(theme: MarkdownTheme) {
   ifShowSeparatorForTitleLevelHelper(theme)
   shouldExpandPropertiesHelper(theme)
   shouldExpandDeclarationChildrenHelper(theme)
+  startSectionsHelper(theme)
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/start-sections.ts

@@ -0,0 +1,22 @@
+import * as Handlebars from "handlebars"
+import { MarkdownTheme } from "../../theme"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper("startSections", function () {
+    const { startSections, shouldIncrementAfterStartSections } =
+      theme.getFormattingOptionsForLocation()
+
+    if (!startSections?.length) {
+      return ""
+    }
+
+    const lineBreaks = "\n\n"
+    const separator = `---${lineBreaks}`
+
+    if (shouldIncrementAfterStartSections) {
+      Handlebars.helpers.incrementCurrentTitleLevel()
+    }
+
+    return `${separator}${startSections.join(`${lineBreaks}${separator}`)}`
+  })
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/templates/index.hbs

@@ -2,6 +2,8 @@
 
 {{incrementCurrentTitleLevel}}
 
+{{{ startSections }}}
+
 {{#with model.readme}}
 
 {{{comment this}}}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/templates/reflection.hbs

@@ -4,6 +4,8 @@
 
 {{incrementCurrentTitleLevel}}
 
+{{{ startSections }}}
+
 {{#with model}}
 
 {{#if (sectionEnabled "reflection_comment")}}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/templates/reflection.member.hbs

@@ -6,6 +6,8 @@
 
 {{incrementCurrentTitleLevel}}
 
+{{{ startSections }}}
+
 {{> member showSources=false}}
 
 {{decrementCurrentTitleLevel}}

www/utils/packages/types/lib/index.d.ts

@@ -75,7 +75,9 @@ export type FormattingOptionType = {
   mdxImports?: string[]
   maxLevel?: number
   fileNameSeparator?: string
+  startSections?: string[]
   endSections?: string[]
+  shouldIncrementAfterStartSections?: boolean
 }
 
 export declare module "typedoc" {