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

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)
-referenceNames.forEach((names) => {
-  const configPathName = path.join(
-    __dirname,
-    "..",
-    "typedoc-config",
-    `${names}.js`
+const require = createRequire(import.meta.url)
+
+const referenceNames = process.argv.slice(2) || ["all"]
+const basePath = path.join(require.resolve("typedoc-config"), "..")
+
+if (!referenceNames.length) {
+  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(
-      `Config file for ${names} doesn't exist. Make sure to create it in ${configPathName}`
+    console.log(
+      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.stderr?.pipe(process.stdout)
-})
+  typedocProcess.stdout?.on("data", (chunk: string) => {
+    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"]
 }