chore(docs-util): Improve generate references script and action (#5472)

* chore(docs-util): Improve generate references script and action

* added if condition for API reference

* fix api reference condition

* fix description of action

* fix body value

* fix step name

.github/workflows/generate-references.yml

@@ -1,11 +1,16 @@
-name: Generate Documentation Reference
+name: Generate Automated Documentation
 on:
   workflow_dispatch:
+    inputs:
+      referenceName:
+        description: 'Reference to Generate. Use either `all` to generate all references, `api` to generate the API reference, or a name of a config file in `docs-util/packages/typedoc-config` such as `product`'
+        required: false
+        default: 'all'
   release:
     types: [published]
 
 jobs:
-  services:
+  references:
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
@@ -40,22 +45,35 @@ jobs:
         run: yarn build
         working-directory: docs-util
 
-      - name: Generate Services Reference
+      - name: Generate References
-        run: yarn generate:reference services
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        run: "yarn generate:reference ${{ github.event.inputs.referenceName }}"
+        working-directory: docs-util/packages/scripts
+
+      - name: Generate References
+        if: ${{ github.event_name != 'workflow_dispatch' }}
+        run: "yarn generate:reference all"
+        working-directory: docs-util/packages/scripts
+
+      - name: Get PR Message
+        id: pr-message
+        run: yarn generate:message
         working-directory: docs-util/packages/scripts
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v4
         with:
-          commit-message: "chore(docs): Generated Services Reference (automated)"
+          commit-message: "chore(docs): Generated References (automated)"
           base: "develop"
-          title: "chore(docs): Generated Services Reference (automated)"
+          title: "chore(docs): Generated References"
           labels: "type: chore"
-          add-paths: www/apps/docs/content/references/services/**
+          add-paths: www/apps/docs/content/references/**
-          branch: "docs/generate-services"
+          branch: "docs/generate-reference"
           branch-suffix: "timestamp"
+          body: ${{ steps.pr-message.outputs.body }}
   api:
     runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'release' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'api' }}
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0
@@ -94,200 +112,4 @@ jobs:
           labels: "type: chore"
           add-paths: www/apps/api-reference/specs
           branch: "docs/generate-api-ref"
-          branch-suffix: "timestamp"
-  entities:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Cancel Previous Runs
-        uses: styfle/cancel-workflow-action@0.11.0
-        with:
-          access_token: ${{ github.token }}
-
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v3
-        with:
-          node-version: "16.20.2"
-          cache: "yarn"
-
-      - name: Install dependencies
-        uses: ./.github/actions/cache-deps
-        with:
-          extension: reference
-
-      - name: Build Packages
-        run: yarn build
-
-      - name: Install Workspace dependencies
-        run: yarn install
-        working-directory: docs-util
-
-      - name: Build Workspace dependencies
-        run: yarn build
-        working-directory: docs-util
-
-      - name: Generate Entities Reference
-        run: yarn generate:reference entities
-        working-directory: docs-util/packages/scripts
-
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: "chore(docs): Generated Entities Reference (automated)"
-          base: "develop"
-          title: "chore(docs): Generated Entities Reference (automated)"
-          labels: "type: chore"
-          add-paths: www/apps/docs/content/references/entities/**
-          branch: "docs/generate-entities"
-          branch-suffix: "timestamp"
-  js-client:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Cancel Previous Runs
-        uses: styfle/cancel-workflow-action@0.11.0
-        with:
-          access_token: ${{ github.token }}
-
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v3
-        with:
-          node-version: "16.20.2"
-          cache: "yarn"
-
-      - name: Install dependencies
-        uses: ./.github/actions/cache-deps
-        with:
-          extension: reference
-
-      - name: Build Packages
-        run: yarn build
-
-      - name: Install Workspace dependencies
-        run: yarn install
-        working-directory: docs-util
-
-      - name: Build Workspace dependencies
-        run: yarn build
-        working-directory: docs-util
-
-      - name: Generate Services Reference
-        run: yarn generate:reference js-client
-        working-directory: docs-util/packages/scripts
-
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: "chore(docs): Generated JS Client Reference (automated)"
-          base: "develop"
-          title: "chore(docs): Generated JS Client Reference"
-          labels: "type: chore"
-          add-paths: www/apps/docs/content/references/js-client/**
-          branch: "docs/generate-js-client"
-          branch-suffix: "timestamp"
-  pricing:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Cancel Previous Runs
-        uses: styfle/cancel-workflow-action@0.11.0
-        with:
-          access_token: ${{ github.token }}
-
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v3
-        with:
-          node-version: "16.20.2"
-          cache: "yarn"
-
-      - name: Install dependencies
-        uses: ./.github/actions/cache-deps
-        with:
-          extension: reference
-
-      - name: Build Packages
-        run: yarn build
-
-      - name: Install Workspace dependencies
-        run: yarn install
-        working-directory: docs-util
-
-      - name: Build Workspace dependencies
-        run: yarn build
-        working-directory: docs-util
-
-      - name: Generate Pricing Module Reference
-        run: yarn generate:reference pricing
-        working-directory: docs-util/packages/scripts
-
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: "chore(docs): Generated Pricing Module Reference (automated)"
-          base: "develop"
-          title: "chore(docs): Generated Pricing Module Reference"
-          labels: "type: chore"
-          add-paths: www/apps/docs/content/references/pricing/**
-          branch: "docs/generate-pricing"
-          branch-suffix: "timestamp"
-  product:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Cancel Previous Runs
-        uses: styfle/cancel-workflow-action@0.11.0
-        with:
-          access_token: ${{ github.token }}
-
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v3
-        with:
-          node-version: "16.20.2"
-          cache: "yarn"
-
-      - name: Install dependencies
-        uses: ./.github/actions/cache-deps
-        with:
-          extension: reference
-
-      - name: Build Packages
-        run: yarn build
-
-      - name: Install Workspace dependencies
-        run: yarn install
-        working-directory: docs-util
-
-      - name: Build Workspace dependencies
-        run: yarn build
-        working-directory: docs-util
-
-      - name: Generate Product Module Reference
-        run: yarn generate:reference product
-        working-directory: docs-util/packages/scripts
-
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: "chore(docs): Generated Product Module Reference (automated)"
-          base: "develop"
-          title: "chore(docs): Generated Product Module Reference"
-          labels: "type: chore"
-          add-paths: www/apps/docs/content/references/product/**
-          branch: "docs/generate-product"
           branch-suffix: "timestamp"

docs-util/packages/scripts/generate-reference.ts

@@ -2,24 +2,80 @@
 import path from "path"
 import fs from "fs"
 import { exec } from "child_process"
+import { globSync } from "glob"
+import randomColor from "randomcolor"
+import chalk, { ChalkInstance } from "chalk"
+import { createRequire } from "node:module"
 
-const referenceNames = process.argv.slice(2)
+const require = createRequire(import.meta.url)
-referenceNames.forEach((names) => {
+
-  const configPathName = path.join(
+const referenceNames = process.argv.slice(2) || ["all"]
-    __dirname,
+const basePath = path.join(require.resolve("typedoc-config"), "..")
-    "..",
+
-    "typedoc-config",
+if (!referenceNames.length) {
-    `${names}.js`
+  console.error(
+    chalk.red(
+      "No reference names specified. Please specify the name of a reference to generate, or use `all` to generate all references."
+    )
   )
+  process.exit(1)
+}
+
+referenceNames.forEach((name) => {
+  if (name === "all") {
+    // generate reference for all configration files in
+    // `typedoc-config` directory, except for files starting
+    // with `_`
+    const files = globSync("[^_]**.js", {
+      cwd: path.join(basePath),
+    })
+    files.forEach((file) => generateReference(file))
+  } else {
+    generateReference(`${name}.js`)
+  }
+})
+
+function generateReference(referenceName: string) {
+  const configPathName = path.join(basePath, referenceName)
 
   // check if the config file exists
   if (!fs.existsSync(configPathName)) {
-    throw new Error(
+    console.log(
-      `Config file for ${names} doesn't exist. Make sure to create it in ${configPathName}`
+      chalk.red(
+        `Config file for ${referenceName} doesn't exist. Make sure to create it in ${configPathName}`
+      )
     )
+    return
   }
 
+  const colorLog = chalk.hex(randomColor())
+  formatColoredLog(colorLog, referenceName, "Generating reference...")
   const typedocProcess = exec(`typedoc --options ${configPathName}`)
-  typedocProcess.stdout?.pipe(process.stdout)
+  typedocProcess.stdout?.on("data", (chunk: string) => {
-  typedocProcess.stderr?.pipe(process.stdout)
+    formatColoredLog(colorLog, referenceName, chunk.trim())
-})
+  })
+  typedocProcess.stderr?.on("data", (chunk: string) => {
+    // split multiline outputs
+    const split: string[] = chunk.split("\n")
+    split.forEach((line: string) => {
+      if (!line.length) {
+        return
+      }
+
+      formatColoredLog(
+        colorLog,
+        referenceName,
+        `${chalk.red("An error occurred")}: ${line.trim()}`
+      )
+    })
+  })
+  formatColoredLog(colorLog, referenceName, "Finished Generating reference.")
+}
+
+function formatColoredLog(
+  chalkInstance: ChalkInstance,
+  title: string,
+  message: string
+) {
+  console.log(`${chalkInstance(title)} -> ${message}`)
+}

docs-util/packages/scripts/get-generate-diff-message.ts

@@ -0,0 +1,27 @@
+import { execSync } from "child_process"
+import * as core from "@actions/core"
+
+const command = `git --no-pager diff --minimal --name-only ../../../www/apps/docs/content/references`
+const diffOutput = execSync(command).toString()
+
+const files = diffOutput.toString().split("\n").filter(Boolean)
+
+const referenceNames: Set<string> = new Set([])
+
+files.forEach((file) => {
+  const referenceName = file
+    .replace("www/apps/docs/content/references/", "")
+    .split("/")[0]
+
+  if (referenceName) {
+    referenceNames.add(referenceName)
+  }
+})
+
+let strOutput = "Generated the following references:\n"
+
+referenceNames.forEach((referenceName) => {
+  strOutput += `- \`${referenceName}\`\n`
+})
+
+core.setOutput("body", strOutput)

docs-util/packages/scripts/package.json

@@ -8,15 +8,22 @@
   "scripts": {
     "generate:announcement": "ts-node ./doc-change-release.ts",
     "generate:reference": "ts-node ./generate-reference.ts",
-    "check:freshness": "ts-node ./freshness-check.ts"
+    "check:freshness": "ts-node ./freshness-check.ts",
+    "generate:message": "ts-node ./get-generate-diff-message.ts"
   },
   "version": "0.0.0",
+  "type": "module",
   "dependencies": {
+    "@actions/core": "^1.10.1",
     "@linear/sdk": "^1.22.0",
     "@octokit/core": "^4.0.5",
     "@types/node": "^20.8.3",
+    "chalk": "^5.3.0",
+    "glob": "^10.3.10",
+    "randomcolor": "^0.6.2",
     "ts-node": "^10.9.1",
     "typedoc": "0.25.1",
+    "typedoc-config": "*",
     "typedoc-monorepo-link-types": "^0.0.2",
     "typedoc-plugin-frontmatter": "*",
     "typedoc-plugin-markdown": "3.16.0",
@@ -27,5 +34,8 @@
     "typedoc-plugin-reference-excluder": "1.1.3",
     "typedoc-plugin-rename-defaults": "^0.6.6",
     "typescript": "^5.2.2"
+  },
+  "devDependencies": {
+    "@types/randomcolor": "^0.5.8"
   }
 }

docs-util/packages/scripts/tsconfig.json

@@ -1,7 +1,12 @@
 {
   "extends": "../../tsconfig",
   "compilerOptions": {
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "module": "ESNext",
+    "moduleResolution": "node",
+  },
+  "include": ["*.ts"],
+  "ts-node": {
+    "esm": true,
   },
-  "include": ["*.ts"]
 }

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

@@ -0,0 +1,4 @@
+module.exports = {
+  plugin: ["typedoc-plugin-markdown-medusa"],
+  readme: "none",
+}

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

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const path = require("path")
-const globalTypedocOptions = require("./base")
+const globalTypedocOptions = require("./_base")
 
 const pathPrefix = path.join(__dirname, "..", "..", "..")
 
@@ -81,7 +81,7 @@ module.exports = ({
     hideInPageTOC: true,
     hideBreadcrumbs: true,
     plugin: [
-      "typedoc-plugin-markdown-medusa",
+      ...globalTypedocOptions.plugin,
       "typedoc-plugin-modules",
       "typedoc-plugin-rename-defaults",
       "typedoc-plugin-frontmatter",

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

@@ -1,4 +0,0 @@
-module.exports = {
-  plugin: ["typedoc-plugin-markdown"],
-  readme: "none",
-}

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

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const path = require("path")
-const globalTypedocOptions = require("./base")
+const globalTypedocOptions = require("./_base")
 
 const pathPrefix = path.join(__dirname, "..", "..", "..")
 
@@ -14,7 +14,7 @@ module.exports = {
   entryDocument: "_index.mdx",
   hideInPageTOC: true,
   hideBreadcrumbs: true,
-  plugin: ["typedoc-plugin-markdown-medusa", "typedoc-plugin-frontmatter"],
+  plugin: [...globalTypedocOptions.plugin, "typedoc-plugin-frontmatter"],
   frontmatterData: {
     displayed_sidebar: "entitiesSidebar",
   },

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

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const path = require("path")
-const globalTypedocOptions = require("./base")
+const globalTypedocOptions = require("./_base")
 
 const pathPrefix = path.join(__dirname, "..", "..", "..")
 
@@ -16,7 +16,7 @@ module.exports = {
   hideInPageTOC: true,
   hideBreadcrumbs: true,
   plugin: [
-    "typedoc-plugin-markdown-medusa",
+    ...globalTypedocOptions.plugin,
     "typedoc-plugin-reference-excluder",
     "typedoc-plugin-frontmatter",
     "typedoc-plugin-rename-defaults",

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

@@ -5,5 +5,6 @@
   "publishConfig": {
     "access": "public"
   },
+  "main": "_base.js",
   "version": "0.0.0"
 }

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

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
-const modulesConfig = require("./modules")
+const modulesConfig = require("./_modules")
 
 module.exports = modulesConfig({
   entryPointPath: "packages/types/src/pricing/service.ts",

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

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
-const modulesConfig = require("./modules")
+const modulesConfig = require("./_modules")
 
 module.exports = modulesConfig({
   entryPointPath: "packages/types/src/product/service.ts",

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

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const path = require("path")
-const globalTypedocOptions = require("./base")
+const globalTypedocOptions = require("./_base")
 
 const pathPrefix = path.join(__dirname, "..", "..", "..")
 

docs-util/yarn.lock

@@ -12,6 +12,26 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@actions/core@npm:^1.10.1":
+  version: 1.10.1
+  resolution: "@actions/core@npm:1.10.1"
+  dependencies:
+    "@actions/http-client": ^2.0.1
+    uuid: ^8.3.2
+  checksum: 7a61446697a23dcad3545cf0634dedbdedf20ae9a0ee6ee977554589a15deb4a93593ee48a41258933d58ce0778f446b0d2c162b60750956fb75e0b9560fb832
+  languageName: node
+  linkType: hard
+
+"@actions/http-client@npm:^2.0.1":
+  version: 2.2.0
+  resolution: "@actions/http-client@npm:2.2.0"
+  dependencies:
+    tunnel: ^0.0.6
+    undici: ^5.25.4
+  checksum: 868fe8529d78beb72f84ea2486e232fa6f66abe00d6ec4591b98c37e762c3d812868a3548638d75b49917961fd10ba1556916b47b1e9e4b55c266e2013c3ae8e
+  languageName: node
+  linkType: hard
+
 "@ampproject/remapping@npm:^2.2.0":
   version: 2.2.1
   resolution: "@ampproject/remapping@npm:2.2.1"
@@ -312,6 +332,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@fastify/busboy@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "@fastify/busboy@npm:2.0.0"
+  checksum: fdaedca865721769a3a8d788c9efd6af90e73b5f2ff0160dbf46a6160631bbe56e6e5770fafb9a6395111372c73fb2bfa8d4698edc98c6b1f7d97cc9b74e37ea
+  languageName: node
+  linkType: hard
+
 "@graphql-typed-document-node/core@npm:^3.1.0":
   version: 3.2.0
   resolution: "@graphql-typed-document-node/core@npm:3.2.0"
@@ -614,6 +641,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/randomcolor@npm:^0.5.8":
+  version: 0.5.8
+  resolution: "@types/randomcolor@npm:0.5.8"
+  checksum: 3812c89dec4c7c8eef1796ff2ab3cd5c2335bf09dea8fe24ebc0ca30403958ea1fd81893cd35b5ae37d8c666b1283bd5a54479faeb1c3f298b39c81189531790
+  languageName: node
+  linkType: hard
+
 "@types/semver@npm:^7.5.0":
   version: 7.5.3
   resolution: "@types/semver@npm:7.5.3"
@@ -963,6 +997,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"chalk@npm:^5.3.0":
+  version: 5.3.0
+  resolution: "chalk@npm:5.3.0"
+  checksum: 8297d436b2c0f95801103ff2ef67268d362021b8210daf8ddbe349695333eb3610a71122172ff3b0272f1ef2cf7cc2c41fdaa4715f52e49ffe04c56340feed09
+  languageName: node
+  linkType: hard
+
 "cliui@npm:^7.0.2":
   version: 7.0.4
   resolution: "cliui@npm:7.0.4"
@@ -2336,6 +2377,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"randomcolor@npm:^0.6.2":
+  version: 0.6.2
+  resolution: "randomcolor@npm:0.6.2"
+  checksum: 845b8b4a31ff4a6fe590930217db93ca5741b0eb7b363c564d5db72d52449383bd4cc44b77b8ae64cf4b70118ef7b8b9062134743e9ec7a6798d6a6f84318a2a
+  languageName: node
+  linkType: hard
+
 "readable-stream@npm:~1.0.31":
   version: 1.0.34
   resolution: "readable-stream@npm:1.0.34"
@@ -2424,11 +2472,17 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "scripts@workspace:packages/scripts"
   dependencies:
+    "@actions/core": ^1.10.1
     "@linear/sdk": ^1.22.0
     "@octokit/core": ^4.0.5
     "@types/node": ^20.8.3
+    "@types/randomcolor": ^0.5.8
+    chalk: ^5.3.0
+    glob: ^10.3.10
+    randomcolor: ^0.6.2
     ts-node: ^10.9.1
     typedoc: 0.25.1
+    typedoc-config: "*"
     typedoc-monorepo-link-types: ^0.0.2
     typedoc-plugin-frontmatter: "*"
     typedoc-plugin-markdown: 3.16.0
@@ -2724,6 +2778,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tunnel@npm:^0.0.6":
+  version: 0.0.6
+  resolution: "tunnel@npm:0.0.6"
+  checksum: e27e7e896f2426c1c747325b5f54efebc1a004647d853fad892b46d64e37591ccd0b97439470795e5262b5c0748d22beb4489a04a0a448029636670bfd801b75
+  languageName: node
+  linkType: hard
+
 "turbo-darwin-64@npm:1.10.14":
   version: 1.10.14
   resolution: "turbo-darwin-64@npm:1.10.14"
@@ -2811,7 +2872,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typedoc-config@workspace:packages/typedoc-config":
+"typedoc-config@*, typedoc-config@workspace:packages/typedoc-config":
   version: 0.0.0-use.local
   resolution: "typedoc-config@workspace:packages/typedoc-config"
   languageName: unknown
@@ -2976,6 +3037,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"undici@npm:^5.25.4":
+  version: 5.26.5
+  resolution: "undici@npm:5.26.5"
+  dependencies:
+    "@fastify/busboy": ^2.0.0
+  checksum: fb4147129abc097a8c7098bb7a29e1026c09c281967efb044041d403985423d09d2b8241e8635b7860f05d8c75565946d8dcc839a3b42804509a3ee56d958716
+  languageName: node
+  linkType: hard
+
 "unfetch@npm:^4.2.0":
   version: 4.2.0
   resolution: "unfetch@npm:4.2.0"
@@ -3027,6 +3097,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"uuid@npm:^8.3.2":
+  version: 8.3.2
+  resolution: "uuid@npm:8.3.2"
+  bin:
+    uuid: dist/bin/uuid
+  checksum: bcbb807a917d374a49f475fae2e87fdca7da5e5530820ef53f65ba1d12131bd81a92ecf259cc7ce317cbe0f289e7d79fdfebcef9bfa3087c8c8a2fa304c9be54
+  languageName: node
+  linkType: hard
+
 "v8-compile-cache-lib@npm:^3.0.1":
   version: 3.0.1
   resolution: "v8-compile-cache-lib@npm:3.0.1"