docs-util: rename docblock-generator to docs-generator (#8331)

* docs-util: rename docblock-generator to docs-generator

* change program name

* fix action

.github/workflows/generate-docblocks.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Run docblock generator
         if: steps.check-commit.outputs.is_release_commit == 'true'
         run: "yarn start run:release --type docs"
-        working-directory: www/utils/packages/docblock-generator
+        working-directory: www/utils/packages/docs-generator
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GIT_OWNER: ${{ github.repository_owner }}

www/utils/.eslintrc.js

@@ -94,7 +94,7 @@ module.exports = {
       parserOptions: {
         project: [
           "./tsconfig.json",
-          "./packages/docblock-generator/tsconfig.json",
+          "./packages/docs-generator/tsconfig.json",
           "./packages/react-docs-generator/tsconfig.json",
           "./packages/scripts/tsconfig.json",
           "./packages/typedoc-generate-references/tsconfig.json",

www/utils/packages/docs-generator/README.md

@@ -1,12 +1,15 @@
-# docblock-generator
+# docs-generator
 
-A CLI tool that can be used to generate TSDoc docblocks and OAS for TypeScript/JavaScript files under the `packages` directory of the main monorepo.
+A CLI tool that generates different types of docblocks from source code:
+
+- Adds TSDocs to any TypeScript file.
+- Generates files with OpenApi Spec comments in `generated/oas-output`.
+- Generates JSON documentation files for models built with Medusa's DML in `generated/dml-output`.
 
 ## Prerequisites
 
 1. Run the `yarn` command to install dependencies.
-2. Copy the `.env.sample` to `.env` and change the `MONOREPO_ROOT_PATH` variable to the absolute path to the monorepo root.
-3. Run the `yarn build` command to build source files.
+2. Run the `yarn build` command to build source files.
 
 ---
 
@@ -17,7 +20,7 @@ A CLI tool that can be used to generate TSDoc docblocks and OAS for TypeScript/J
 Run the following command to run the tool for a specific file:
 
 ```bash
-yarn start run /absolute/path/to/file.ts
+yarn dev run /absolute/path/to/file.ts
 ```
 
 ### Generate for git-changed files
@@ -25,7 +28,7 @@ yarn start run /absolute/path/to/file.ts
 Run the following command to run the tool for applicable git file changes:
 
 ```bash
-yarn start run:changes
+yarn dev run:changes
 ```
 
 ### Generate for a specific commit
@@ -33,7 +36,7 @@ yarn start run:changes
 Run the following command to run the tool for a commit SHA hash:
 
 ```bash
-yarn start run:commit <commit-sha>
+yarn dev run:commit <commit-sha>
 ```
 
 Where `<commit-sha>` is the SHA of the commit. For example, `e28fa7fbdf45c5b1fa19848db731132a0bf1757d`.
@@ -43,7 +46,7 @@ Where `<commit-sha>` is the SHA of the commit. For example, `e28fa7fbdf45c5b1fa1
 Run the following command to run the tool on commits since the latest release.
 
 ```bash
-yarn start run:release
+yarn dev run:release
 ```
 
 ### Clean OAS
@@ -51,11 +54,19 @@ yarn start run:release
 Run the following command to clean up the OAS output files and remove any routes that no longer exist:
 
 ```bash
-yarn start clean:oas
+yarn dev clean:oas
 ```
 
 This command will also remove tags and schemas not used.
 
+### Clean DML JSON files
+
+Run the following command to clean up the DML JSON output files and remove any data models that no longer exist:
+
+```bash
+yarn dev clean:dml
+```
+
 ---
 
 ## How it Works
@@ -64,11 +75,17 @@ This command will also remove tags and schemas not used.
 
 If a node is an API route, it generates OAS comments rather than TSDoc comments. The OAS comments are generated and placed in new/existing files under the `www/utils/generated/oas-output/operations` directory.
 
+## Models Built with DML
+
+If a node is a `CallExpression` and it's created using `model.define`, then a JSON documentation file with key-value pairs is generated to add description to its properties.
+
+Only files under `packages/modules/**/src/models` are considered here.
+
 ### Generating TSDoc Docblocks
 
-If a note isn't an API Route and it complies with the specified conditions, TSDoc docblocks are generated for it. 
+If a node isn't an API Route and it complies with the specified conditions, TSDoc docblocks are generated for it. 
 
-Files under the `packages/medusa/src/api` or `api-v2` directories are considered incompatible, so any files under these directories won't have TSDoc docblocks generated for them.
+Files under the `packages/medusa/src/api` or `packages/modules/**/src/models` directories are considered incompatible, so any files under these directories won't have TSDoc docblocks generated for them.
 
 ---
 
@@ -88,4 +105,5 @@ You can use this option to specify the type of docs to generate. Possible values
 
 - `all`: (default) Generate all doc types.
 - `docs`: Generate only TSDoc docblocks.
-- `oas`: Generate only OAS docblocks/files.
+- `oas`: Generate only OAS files.
+- `dml`: Generate only JSON files for models built with DML.

www/utils/packages/docs-generator/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "docblock-generator",
+  "name": "docs-generator",
   "license": "MIT",
   "scripts": {
     "dev": "node --loader ts-node/esm src/index.ts",

www/utils/packages/docs-generator/src/classes/generators/docblock.ts

@@ -167,6 +167,9 @@ class DocblockGenerator extends AbstractGenerator {
       super.isFileIncluded(fileName) &&
       !minimatch(getBasePath(fileName), "packages/medusa/**/api**/**", {
         matchBase: true,
+      }) &&
+      !minimatch(getBasePath(fileName), "packages/modules/**/models/**", {
+        matchBase: true,
       })
     )
   }

www/utils/packages/docs-generator/src/classes/kinds/oas.ts

@@ -25,7 +25,7 @@ import FunctionKindGenerator, {
   FunctionOrVariableNode,
   VariableNode,
 } from "./function.js"
-import { API_ROUTE_PARAM_REGEX } from "../helpers/../../constants.js"
+import { API_ROUTE_PARAM_REGEX } from "../../constants.js"
 
 const RES_STATUS_REGEX = /^res[\s\S]*\.status\((\d+)\)/
 

www/utils/packages/docs-generator/src/index.ts

@@ -10,7 +10,7 @@ import cleanDml from "./commands/clean-dml.js"
 
 const program = new Command()
 
-program.name("docblock-generator").description("Generate TSDoc doc-blocks")
+program.name("docs-generator").description("Generate TSDoc doc-blocks")
 
 // define common options
 const typeOption = new Option("--type <type>", "The type of docs to generate.")

www/utils/yarn.lock

@@ -2343,9 +2343,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"docblock-generator@workspace:packages/docblock-generator":
+"docs-generator@workspace:packages/docs-generator":
   version: 0.0.0-use.local
-  resolution: "docblock-generator@workspace:packages/docblock-generator"
+  resolution: "docs-generator@workspace:packages/docs-generator"
   dependencies:
     "@faker-js/faker": ^8.4.0
     "@octokit/core": ^5.0.2