diff --git a/.github/workflows/generate-references.yml b/.github/workflows/generate-references.yml index f28c9cc084..046cfe9f52 100644 --- a/.github/workflows/generate-references.yml +++ b/.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 - run: yarn generate:reference services + - name: Generate References + 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/** - branch: "docs/generate-services" + add-paths: www/apps/docs/content/references/** + 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" \ No newline at end of file diff --git a/docs-util/packages/scripts/generate-reference.ts b/docs-util/packages/scripts/generate-reference.ts index ced3ccb390..4f9b6bb8fa 100644 --- a/docs-util/packages/scripts/generate-reference.ts +++ b/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}`) +} diff --git a/docs-util/packages/scripts/get-generate-diff-message.ts b/docs-util/packages/scripts/get-generate-diff-message.ts new file mode 100644 index 0000000000..c627ddb8a4 --- /dev/null +++ b/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 = 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) diff --git a/docs-util/packages/scripts/package.json b/docs-util/packages/scripts/package.json index be40691b47..8d79484e3f 100644 --- a/docs-util/packages/scripts/package.json +++ b/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" } } diff --git a/docs-util/packages/scripts/tsconfig.json b/docs-util/packages/scripts/tsconfig.json index 63cce9c4ce..f7e665da88 100644 --- a/docs-util/packages/scripts/tsconfig.json +++ b/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"] } \ No newline at end of file diff --git a/docs-util/packages/typedoc-config/_base.js b/docs-util/packages/typedoc-config/_base.js new file mode 100644 index 0000000000..d33bad6b31 --- /dev/null +++ b/docs-util/packages/typedoc-config/_base.js @@ -0,0 +1,4 @@ +module.exports = { + plugin: ["typedoc-plugin-markdown-medusa"], + readme: "none", +} diff --git a/docs-util/packages/typedoc-config/modules.js b/docs-util/packages/typedoc-config/_modules.js similarity index 97% rename from docs-util/packages/typedoc-config/modules.js rename to docs-util/packages/typedoc-config/_modules.js index 1b43bb6105..8c776926bf 100644 --- a/docs-util/packages/typedoc-config/modules.js +++ b/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", diff --git a/docs-util/packages/typedoc-config/base.js b/docs-util/packages/typedoc-config/base.js deleted file mode 100644 index b0f340b2d9..0000000000 --- a/docs-util/packages/typedoc-config/base.js +++ /dev/null @@ -1,4 +0,0 @@ -module.exports = { - plugin: ["typedoc-plugin-markdown"], - readme: "none", -} diff --git a/docs-util/packages/typedoc-config/entities.js b/docs-util/packages/typedoc-config/entities.js index 70c9e059c3..54264a7fb0 100644 --- a/docs-util/packages/typedoc-config/entities.js +++ b/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", }, diff --git a/docs-util/packages/typedoc-config/js-client.js b/docs-util/packages/typedoc-config/js-client.js index 3eb24da4ea..916ee03e80 100644 --- a/docs-util/packages/typedoc-config/js-client.js +++ b/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", diff --git a/docs-util/packages/typedoc-config/package.json b/docs-util/packages/typedoc-config/package.json index e967a4691c..2942c2c8d3 100644 --- a/docs-util/packages/typedoc-config/package.json +++ b/docs-util/packages/typedoc-config/package.json @@ -5,5 +5,6 @@ "publishConfig": { "access": "public" }, + "main": "_base.js", "version": "0.0.0" } diff --git a/docs-util/packages/typedoc-config/pricing.js b/docs-util/packages/typedoc-config/pricing.js index 3df1dbe1bd..eb4eb97481 100644 --- a/docs-util/packages/typedoc-config/pricing.js +++ b/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", diff --git a/docs-util/packages/typedoc-config/product.js b/docs-util/packages/typedoc-config/product.js index 3393f8106c..f6e235c387 100644 --- a/docs-util/packages/typedoc-config/product.js +++ b/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", diff --git a/docs-util/packages/typedoc-config/services.js b/docs-util/packages/typedoc-config/services.js index 4d46058d77..aa59b445ca 100644 --- a/docs-util/packages/typedoc-config/services.js +++ b/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, "..", "..", "..") diff --git a/docs-util/yarn.lock b/docs-util/yarn.lock index 254567439e..a2b0bf9f36 100644 --- a/docs-util/yarn.lock +++ b/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"