diff --git a/.config/typedoc.workspace.js b/.config/typedoc.workspace.js new file mode 100644 index 000000000..24a534591 --- /dev/null +++ b/.config/typedoc.workspace.js @@ -0,0 +1,52 @@ +// @ts-check + +const path = require('node:path'); +const fs = require('node:fs'); + +/** + * Generates `entryPoints` for TypeDoc for a workspace. + * + * This inspects exports for the `typedoc` conditional, and uses that, if + * present. + * + * This does not recurse exports. + * + * @param {string} cwd + * @returns {Partial} + */ +module.exports = function (cwd) { + /** + * @type {import('type-fest').PackageJson} + */ + const pkgJson = JSON.parse( + fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'), + ); + const {exports} = pkgJson; + if (!exports) { + throw new TypeError('package.json does not have exports'); + } + if (typeof exports !== 'object') { + throw new TypeError('package.json exports is not an object'); + } + + return { + entryPoints: Object.values(exports) + .filter( + (entryPoint) => + entryPoint && + typeof entryPoint === 'object' && + 'typedoc' in entryPoint && + typeof entryPoint.typedoc === 'string', + ) + .map((entryPoint) => + path.join( + cwd, + /** + * @type {{typedoc: string}} + */ (entryPoint).typedoc, + ), + ), + excludeInternal: true, + excludePrivate: true, + }; +}; diff --git a/package-lock.json b/package-lock.json index e47bccd87..1fa01842c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -44,6 +44,8 @@ "sinon": "16.1.3", "snap-shot-it": "7.9.10", "ts-node": "10.9.2", + "typedoc": "0.25.3", + "typedoc-plugin-zod": "1.1.0", "typescript": "5.2.2", "unexpected": "13.2.1", "unexpected-sinon": "11.1.0" @@ -1195,6 +1197,12 @@ "node": ">=8" } }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -4391,6 +4399,12 @@ "json5": "lib/cli.js" } }, + "node_modules/jsonc-parser": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", + "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==", + "dev": true + }, "node_modules/jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -4880,6 +4894,12 @@ "node": ">=10" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/magicpen": { "version": "6.2.4", "resolved": "https://registry.npmjs.org/magicpen/-/magicpen-6.2.4.tgz", @@ -5085,6 +5105,18 @@ "node": ">=16" } }, + "node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, "node_modules/md5.js": { "version": "1.3.5", "resolved": "https://registry.npmjs.org/md5.js/-/md5.js-1.3.5.tgz", @@ -7511,6 +7543,18 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/shiki": { + "version": "0.14.6", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.6.tgz", + "integrity": "sha512-R4koBBlQP33cC8cpzX0hAoOURBHJILp4Aaduh2eYi+Vj8ZBqtK/5SWNEHBS3qwUMu8dqOtI/ftno3ESfNeVW9g==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, "node_modules/shx": { "version": "0.3.4", "resolved": "https://registry.npmjs.org/shx/-/shx-0.3.4.tgz", @@ -8383,6 +8427,60 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/typedoc": { + "version": "0.25.3", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.3.tgz", + "integrity": "sha512-Ow8Bo7uY1Lwy7GTmphRIMEo6IOZ+yYUyrc8n5KXIZg1svpqhZSWgni2ZrDhe+wLosFS8yswowUzljTAV/3jmWw==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.3", + "shiki": "^0.14.1" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 16" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x" + } + }, + "node_modules/typedoc-plugin-zod": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/typedoc-plugin-zod/-/typedoc-plugin-zod-1.1.0.tgz", + "integrity": "sha512-LaQdkYyVVL8CX+4R0GJuOyDa1meiG3M85FiBTPvlikCGaRkTNGSEBZTbx3gQHAsNQ5NWJpLvYJQB6gMhcO8bWw==", + "dev": true, + "peerDependencies": { + "typedoc": "0.23.x || 0.24.x || 0.25.x" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "5.2.2", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.2.2.tgz", @@ -8653,6 +8751,18 @@ "integrity": "sha512-2ham8XPWTONajOR0ohOKOHXkm3+gaBmGut3SRuu75xLd/RRaY6vqgh8NBYYk7+RW3u5AtzPQZG8F10LHkl0lAQ==", "dev": true }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + }, "node_modules/wcwidth": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/wcwidth/-/wcwidth-1.0.1.tgz", diff --git a/package.json b/package.json index a983d2f0d..a2e951f98 100644 --- a/package.json +++ b/package.json @@ -76,6 +76,8 @@ "sinon": "16.1.3", "snap-shot-it": "7.9.10", "ts-node": "10.9.2", + "typedoc": "0.25.3", + "typedoc-plugin-zod": "1.1.0", "typescript": "5.2.2", "unexpected": "13.2.1", "unexpected-sinon": "11.1.0" diff --git a/packages/midnight-smoker/.config/typedoc.js b/packages/midnight-smoker/.config/typedoc.js new file mode 100644 index 000000000..b9bb2d6b4 --- /dev/null +++ b/packages/midnight-smoker/.config/typedoc.js @@ -0,0 +1,5 @@ +const path = require('node:path'); + +module.exports = require('../../../.config/typedoc.workspace')( + path.resolve(__dirname, '..'), +); diff --git a/packages/test-util/.config/typedoc.js b/packages/test-util/.config/typedoc.js new file mode 100644 index 000000000..b9bb2d6b4 --- /dev/null +++ b/packages/test-util/.config/typedoc.js @@ -0,0 +1,5 @@ +const path = require('node:path'); + +module.exports = require('../../../.config/typedoc.workspace')( + path.resolve(__dirname, '..'), +); diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 000000000..8a398a933 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": [ + "./packages/midnight-smoker", + "./packages/plugin-default", + "./packages/test-util" + ], + "out": "docs/api", + "entryPointStrategy": "packages", + "plugin": ["typedoc-plugin-zod"], + "excludeInternal": true, + "excludePrivate": true, + "cleanOutputDir": true, + "logLevel": "Info" +}