From a77185a6a4f5746c15f929748581197b419121f1 Mon Sep 17 00:00:00 2001 From: MapleLeaf <19603573+itsMapleLeaf@users.noreply.github.com> Date: Sun, 9 Jan 2022 02:32:23 -0600 Subject: [PATCH] generate api docs --- packages/docs/.gitignore | 1 + packages/docs/package.json | 5 +- packages/docs/src/api/serve-api-docs.ts | 29 +++ packages/docs/src/main.tsx | 2 + packages/docs/typedoc.json | 12 ++ pnpm-lock.yaml | 245 +++++++++++++++++++++++- 6 files changed, 286 insertions(+), 8 deletions(-) create mode 100644 packages/docs/src/api/serve-api-docs.ts create mode 100644 packages/docs/typedoc.json diff --git a/packages/docs/.gitignore b/packages/docs/.gitignore index 33e6952..670b534 100644 --- a/packages/docs/.gitignore +++ b/packages/docs/.gitignore @@ -1,2 +1,3 @@ .asset-cache node_modules +/api diff --git a/packages/docs/package.json b/packages/docs/package.json index 80682c1..6139422 100644 --- a/packages/docs/package.json +++ b/packages/docs/package.json @@ -31,11 +31,12 @@ "pino-colada": "^2.2.2", "pino-http": "^6.5.0", "postcss": "^8.4.5", - "react-ssr-prepass": "^1.5.0", "reacord": "workspace:*", "react": "^18.0.0-rc.0", "react-dom": "^18.0.0-rc.0", - "tailwindcss": "^3.0.8" + "react-ssr-prepass": "^1.5.0", + "tailwindcss": "^3.0.8", + "typedoc": "^0.22.10" }, "devDependencies": { "@types/browser-sync": "^2.26.3", diff --git a/packages/docs/src/api/serve-api-docs.ts b/packages/docs/src/api/serve-api-docs.ts new file mode 100644 index 0000000..a05b39d --- /dev/null +++ b/packages/docs/src/api/serve-api-docs.ts @@ -0,0 +1,29 @@ +import express, { RequestHandler } from "express" +import PromiseRouter from "express-promise-router" +import * as TypeDoc from "typedoc" + +let built = false +const outputDir = "api" + +export function serveApiDocs(): RequestHandler { + return PromiseRouter() + .use(async (_, __, next) => { + if (!built) { + const app = new TypeDoc.Application() + app.options.addReader(new TypeDoc.TSConfigReader()) + app.options.addReader(new TypeDoc.TypeDocReader()) + app.bootstrap() + + const project = app.convert() + + if (!project) { + throw new Error("Failed to convert project") + } + + await app.generateDocs(project, outputDir) + built = true + } + next() + }) + .use(express.static(outputDir)) +} diff --git a/packages/docs/src/main.tsx b/packages/docs/src/main.tsx index 97ad352..ff855a5 100644 --- a/packages/docs/src/main.tsx +++ b/packages/docs/src/main.tsx @@ -6,6 +6,7 @@ import httpTerminator from "http-terminator" import pino from "pino" import pinoHttp from "pino-http" import * as React from "react" +import { serveApiDocs } from "./api/serve-api-docs" import { AssetBuilder } from "./asset-builder/asset-builder.js" import { fromProjectRoot } from "./constants" import { GuidePage } from "./guides/guide-page" @@ -24,6 +25,7 @@ const router = PromiseRouter() .use(pinoHttp({ logger })) .use(compression()) .use(builder.middleware()) + .use("/api", serveApiDocs()) .get("/guides/*", async (req: Request<{ 0: string }>, res) => { res diff --git a/packages/docs/typedoc.json b/packages/docs/typedoc.json new file mode 100644 index 0000000..511a3dd --- /dev/null +++ b/packages/docs/typedoc.json @@ -0,0 +1,12 @@ +{ + "entryPoints": ["../reacord/library/main.ts"], + "out": ["public/docs/api"], + "tsconfig": "../reacord/tsconfig.json", + "excludeInternal": true, + "excludePrivate": true, + "excludeProtected": true, + "categorizeByGroup": false, + "preserveWatchOutput": true, + "githubPages": false, + "readme": "none" +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index bcaa54a..baf98c0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -80,6 +80,7 @@ importers: tailwindcss: ^3.0.8 tsup: ^5.11.10 type-fest: ^2.8.0 + typedoc: ^0.22.10 typescript: ^4.5.4 wait-on: ^6.0.0 dependencies: @@ -91,7 +92,7 @@ importers: compression: 1.7.4 cross-env: 7.0.3 cssnano: 5.0.15_postcss@8.4.5 - esbuild: 0.14.10 + esbuild: 0.14.11 esno: 0.13.0_typescript@4.5.4 express: 4.17.2 express-promise-router: 4.1.1_1b803edea6f06711ee906a90f400b6a4 @@ -126,6 +127,7 @@ importers: rxjs: 7.5.1 tsup: 5.11.10_typescript@4.5.4 type-fest: 2.8.0 + typedoc: 0.22.10_typescript@4.5.4 typescript: 4.5.4 wait-on: 6.0.0 @@ -2107,6 +2109,14 @@ packages: esbuild: 0.14.10 dev: true + /bundle-require/2.2.0_esbuild@0.14.11: + resolution: {integrity: sha512-JDVxYEAxEX1g8AWtadiIkCkFf42RulEl5AOIvUa4cpuEL/VKpK2lJwogyswHnp+qizNQxM0Ylamw7CjPRaJZuA==} + peerDependencies: + esbuild: '>=0.13' + dependencies: + esbuild: 0.14.11 + dev: true + /bytes/3.0.0: resolution: {integrity: sha1-0ygVQE1olpn4Wk6k+odV3ROpYEg=} engines: {node: '>= 0.8'} @@ -3159,6 +3169,14 @@ packages: cpu: [arm64] os: [android] requiresBuild: true + dev: true + optional: true + + /esbuild-android-arm64/0.14.11: + resolution: {integrity: sha512-6iHjgvMnC/SzDH8TefL+/3lgCjYWwAd1LixYfmz/TBPbDQlxcuSkX0yiQgcJB9k+ibZ54yjVXziIwGdlc+6WNw==} + cpu: [arm64] + os: [android] + requiresBuild: true optional: true /esbuild-darwin-64/0.14.10: @@ -3166,6 +3184,14 @@ packages: cpu: [x64] os: [darwin] requiresBuild: true + dev: true + optional: true + + /esbuild-darwin-64/0.14.11: + resolution: {integrity: sha512-olq84ikh6TiBcrs3FnM4eR5VPPlcJcdW8BnUz/lNoEWYifYQ+Po5DuYV1oz1CTFMw4k6bQIZl8T3yxL+ZT2uvQ==} + cpu: [x64] + os: [darwin] + requiresBuild: true optional: true /esbuild-darwin-arm64/0.14.10: @@ -3173,6 +3199,14 @@ packages: cpu: [arm64] os: [darwin] requiresBuild: true + dev: true + optional: true + + /esbuild-darwin-arm64/0.14.11: + resolution: {integrity: sha512-Jj0ieWLREPBYr/TZJrb2GFH8PVzDqiQWavo1pOFFShrcmHWDBDrlDxPzEZ67NF/Un3t6sNNmeI1TUS/fe1xARg==} + cpu: [arm64] + os: [darwin] + requiresBuild: true optional: true /esbuild-freebsd-64/0.14.10: @@ -3180,6 +3214,14 @@ packages: cpu: [x64] os: [freebsd] requiresBuild: true + dev: true + optional: true + + /esbuild-freebsd-64/0.14.11: + resolution: {integrity: sha512-C5sT3/XIztxxz/zwDjPRHyzj/NJFOnakAanXuyfLDwhwupKPd76/PPHHyJx6Po6NI6PomgVp/zi6GRB8PfrOTA==} + cpu: [x64] + os: [freebsd] + requiresBuild: true optional: true /esbuild-freebsd-arm64/0.14.10: @@ -3187,6 +3229,14 @@ packages: cpu: [arm64] os: [freebsd] requiresBuild: true + dev: true + optional: true + + /esbuild-freebsd-arm64/0.14.11: + resolution: {integrity: sha512-y3Llu4wbs0bk4cwjsdAtVOesXb6JkdfZDLKMt+v1U3tOEPBdSu6w8796VTksJgPfqvpX22JmPLClls0h5p+L9w==} + cpu: [arm64] + os: [freebsd] + requiresBuild: true optional: true /esbuild-jest/0.5.0_esbuild@0.14.10: @@ -3207,6 +3257,14 @@ packages: cpu: [ia32] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-32/0.14.11: + resolution: {integrity: sha512-Cg3nVsxArjyLke9EuwictFF3Sva+UlDTwHIuIyx8qpxRYAOUTmxr2LzYrhHyTcGOleLGXUXYsnUVwKqnKAgkcg==} + cpu: [ia32] + os: [linux] + requiresBuild: true optional: true /esbuild-linux-64/0.14.10: @@ -3214,6 +3272,14 @@ packages: cpu: [x64] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-64/0.14.11: + resolution: {integrity: sha512-oeR6dIrrojr8DKVrxtH3xl4eencmjsgI6kPkDCRIIFwv4p+K7ySviM85K66BN01oLjzthpUMvBVfWSJkBLeRbg==} + cpu: [x64] + os: [linux] + requiresBuild: true optional: true /esbuild-linux-arm/0.14.10: @@ -3221,6 +3287,14 @@ packages: cpu: [arm] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-arm/0.14.11: + resolution: {integrity: sha512-vcwskfD9g0tojux/ZaTJptJQU3a7YgTYsptK1y6LQ/rJmw7U5QJvboNawqM98Ca3ToYEucfCRGbl66OTNtp6KQ==} + cpu: [arm] + os: [linux] + requiresBuild: true optional: true /esbuild-linux-arm64/0.14.10: @@ -3228,6 +3302,14 @@ packages: cpu: [arm64] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-arm64/0.14.11: + resolution: {integrity: sha512-+e6ZCgTFQYZlmg2OqLkg1jHLYtkNDksxWDBWNtI4XG4WxuOCUErLqfEt9qWjvzK3XBcCzHImrajkUjO+rRkbMg==} + cpu: [arm64] + os: [linux] + requiresBuild: true optional: true /esbuild-linux-mips64le/0.14.10: @@ -3235,6 +3317,14 @@ packages: cpu: [mips64el] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-mips64le/0.14.11: + resolution: {integrity: sha512-Rrs99L+p54vepmXIb87xTG6ukrQv+CzrM8eoeR+r/OFL2Rg8RlyEtCeshXJ2+Q66MXZOgPJaokXJZb9snq28bw==} + cpu: [mips64el] + os: [linux] + requiresBuild: true optional: true /esbuild-linux-ppc64le/0.14.10: @@ -3242,6 +3332,14 @@ packages: cpu: [ppc64] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-ppc64le/0.14.11: + resolution: {integrity: sha512-JyzziGAI0D30Vyzt0HDihp4s1IUtJ3ssV2zx9O/c+U/dhUHVP2TmlYjzCfCr2Q6mwXTeloDcLS4qkyvJtYptdQ==} + cpu: [ppc64] + os: [linux] + requiresBuild: true optional: true /esbuild-linux-s390x/0.14.10: @@ -3249,6 +3347,14 @@ packages: cpu: [s390x] os: [linux] requiresBuild: true + dev: true + optional: true + + /esbuild-linux-s390x/0.14.11: + resolution: {integrity: sha512-DoThrkzunZ1nfRGoDN6REwmo8ZZWHd2ztniPVIR5RMw/Il9wiWEYBahb8jnMzQaSOxBsGp0PbyJeVLTUatnlcw==} + cpu: [s390x] + os: [linux] + requiresBuild: true optional: true /esbuild-netbsd-64/0.14.10: @@ -3256,6 +3362,14 @@ packages: cpu: [x64] os: [netbsd] requiresBuild: true + dev: true + optional: true + + /esbuild-netbsd-64/0.14.11: + resolution: {integrity: sha512-12luoRQz+6eihKYh1zjrw0CBa2aw3twIiHV/FAfjh2NEBDgJQOY4WCEUEN+Rgon7xmLh4XUxCQjnwrvf8zhACw==} + cpu: [x64] + os: [netbsd] + requiresBuild: true optional: true /esbuild-node-loader/0.6.3_typescript@4.5.4: @@ -3263,7 +3377,7 @@ packages: peerDependencies: typescript: ^4.0 dependencies: - esbuild: 0.14.10 + esbuild: 0.14.11 typescript: 4.5.4 /esbuild-openbsd-64/0.14.10: @@ -3271,6 +3385,14 @@ packages: cpu: [x64] os: [openbsd] requiresBuild: true + dev: true + optional: true + + /esbuild-openbsd-64/0.14.11: + resolution: {integrity: sha512-l18TZDjmvwW6cDeR4fmizNoxndyDHamGOOAenwI4SOJbzlJmwfr0jUgjbaXCUuYVOA964siw+Ix+A+bhALWg8Q==} + cpu: [x64] + os: [openbsd] + requiresBuild: true optional: true /esbuild-register/3.3.1_esbuild@0.14.10: @@ -3279,12 +3401,29 @@ packages: esbuild: '>=0.12 <1' dependencies: esbuild: 0.14.10 + dev: true + + /esbuild-register/3.3.1_esbuild@0.14.11: + resolution: {integrity: sha512-DjK9rOeo+Dhq8DXKy52DF2+O7zNPXkFRg9lZfqXDGLU6AzrULxBJZPOOFcH6WCNfkwqymKOZoNvd/ncCvEjwdw==} + peerDependencies: + esbuild: '>=0.12 <1' + dependencies: + esbuild: 0.14.11 + dev: false /esbuild-sunos-64/0.14.10: resolution: {integrity: sha512-mEU+pqkhkhbwpJj5DiN3vL0GUFR/yrL3qj8ER1amIVyRibKbj02VM1QaIuk1sy5DRVIKiFXXgCaHvH3RNWCHIw==} cpu: [x64] os: [sunos] requiresBuild: true + dev: true + optional: true + + /esbuild-sunos-64/0.14.11: + resolution: {integrity: sha512-bmYzDtwASBB8c+0/HVOAiE9diR7+8zLm/i3kEojUH2z0aIs6x/S4KiTuT5/0VKJ4zk69kXel1cNWlHBMkmavQg==} + cpu: [x64] + os: [sunos] + requiresBuild: true optional: true /esbuild-windows-32/0.14.10: @@ -3292,6 +3431,14 @@ packages: cpu: [ia32] os: [win32] requiresBuild: true + dev: true + optional: true + + /esbuild-windows-32/0.14.11: + resolution: {integrity: sha512-J1Ys5hMid8QgdY00OBvIolXgCQn1ARhYtxPnG6ESWNTty3ashtc4+As5nTrsErnv8ZGUcWZe4WzTP/DmEVX1UQ==} + cpu: [ia32] + os: [win32] + requiresBuild: true optional: true /esbuild-windows-64/0.14.10: @@ -3299,6 +3446,14 @@ packages: cpu: [x64] os: [win32] requiresBuild: true + dev: true + optional: true + + /esbuild-windows-64/0.14.11: + resolution: {integrity: sha512-h9FmMskMuGeN/9G9+LlHPAoiQk9jlKDUn9yA0MpiGzwLa82E7r1b1u+h2a+InprbSnSLxDq/7p5YGtYVO85Mlg==} + cpu: [x64] + os: [win32] + requiresBuild: true optional: true /esbuild-windows-arm64/0.14.10: @@ -3306,6 +3461,14 @@ packages: cpu: [arm64] os: [win32] requiresBuild: true + dev: true + optional: true + + /esbuild-windows-arm64/0.14.11: + resolution: {integrity: sha512-dZp7Krv13KpwKklt9/1vBFBMqxEQIO6ri7Azf8C+ob4zOegpJmha2XY9VVWP/OyQ0OWk6cEeIzMJwInRZrzBUQ==} + cpu: [arm64] + os: [win32] + requiresBuild: true optional: true /esbuild/0.14.10: @@ -3331,6 +3494,31 @@ packages: esbuild-windows-32: 0.14.10 esbuild-windows-64: 0.14.10 esbuild-windows-arm64: 0.14.10 + dev: true + + /esbuild/0.14.11: + resolution: {integrity: sha512-xZvPtVj6yecnDeFb3KjjCM6i7B5TCAQZT77kkW/CpXTMnd6VLnRPKrUB1XHI1pSq6a4Zcy3BGueQ8VljqjDGCg==} + hasBin: true + requiresBuild: true + optionalDependencies: + esbuild-android-arm64: 0.14.11 + esbuild-darwin-64: 0.14.11 + esbuild-darwin-arm64: 0.14.11 + esbuild-freebsd-64: 0.14.11 + esbuild-freebsd-arm64: 0.14.11 + esbuild-linux-32: 0.14.11 + esbuild-linux-64: 0.14.11 + esbuild-linux-arm: 0.14.11 + esbuild-linux-arm64: 0.14.11 + esbuild-linux-mips64le: 0.14.11 + esbuild-linux-ppc64le: 0.14.11 + esbuild-linux-s390x: 0.14.11 + esbuild-netbsd-64: 0.14.11 + esbuild-openbsd-64: 0.14.11 + esbuild-sunos-64: 0.14.11 + esbuild-windows-32: 0.14.11 + esbuild-windows-64: 0.14.11 + esbuild-windows-arm64: 0.14.11 /escalade/3.1.1: resolution: {integrity: sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==} @@ -3631,9 +3819,9 @@ packages: hasBin: true dependencies: cross-spawn: 7.0.3 - esbuild: 0.14.10 + esbuild: 0.14.11 esbuild-node-loader: 0.6.3_typescript@4.5.4 - esbuild-register: 3.3.1_esbuild@0.14.10 + esbuild-register: 3.3.1_esbuild@0.14.11 import-meta-resolve: 1.1.1 transitivePeerDependencies: - typescript @@ -5606,6 +5794,10 @@ packages: minimist: 1.2.5 dev: true + /jsonc-parser/3.0.0: + resolution: {integrity: sha512-fQzRfAbIBnR0IQvftw9FJveWiHp72Fg20giDrHz6TdfB12UH/uue0D3hm57UB5KgAVuniLMCaS8P1IMj9NR7cA==} + dev: true + /jsonfile/3.0.1: resolution: {integrity: sha1-pezG9l9T9mLEQVx2daAzHQmS7GY=} optionalDependencies: @@ -5817,6 +6009,10 @@ packages: dependencies: yallist: 4.0.0 + /lunr/2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + dev: true + /make-dir/3.1.0: resolution: {integrity: sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==} engines: {node: '>=8'} @@ -5857,6 +6053,12 @@ packages: uc.micro: 1.0.6 dev: false + /marked/3.0.8: + resolution: {integrity: sha512-0gVrAjo5m0VZSJb4rpL59K1unJAMb/hm8HRXqasD8VeC8m91ytDPMritgFSlKonfdt+rRYYpP/JfLxgIX8yoSw==} + engines: {node: '>= 12'} + hasBin: true + dev: true + /mdn-data/2.0.14: resolution: {integrity: sha512-dn6wd0uw5GsdswPFfsgMp5NSB0/aDe6fK94YJV/AJDYXL6HVLWBsxeq7js7Ad+mU2K9LAlwpk6kN2D5mwCPVow==} dev: false @@ -7654,6 +7856,14 @@ packages: resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==} engines: {node: '>=8'} + /shiki/0.9.15: + resolution: {integrity: sha512-/Y0z9IzhJ8nD9nbceORCqu6NgT9X6I8Fk8c3SICHI5NbZRLdZYFaB233gwct9sU0vvSypyaL/qaKvzyQGJBZSw==} + dependencies: + jsonc-parser: 3.0.0 + vscode-oniguruma: 1.6.1 + vscode-textmate: 5.2.0 + dev: true + /side-channel/1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} dependencies: @@ -8308,11 +8518,11 @@ packages: typescript: optional: true dependencies: - bundle-require: 2.2.0_esbuild@0.14.10 + bundle-require: 2.2.0_esbuild@0.14.11 cac: 6.7.12 chokidar: 3.5.2 debug: 4.3.3 - esbuild: 0.14.10 + esbuild: 0.14.11 execa: 5.1.1 globby: 11.0.4 joycon: 3.1.1 @@ -8423,6 +8633,21 @@ packages: is-typedarray: 1.0.0 dev: true + /typedoc/0.22.10_typescript@4.5.4: + resolution: {integrity: sha512-hQYZ4WtoMZ61wDC6w10kxA42+jclWngdmztNZsDvIz7BMJg7F2xnT+uYsUa7OluyKossdFj9E9Ye4QOZKTy8SA==} + engines: {node: '>= 12.10.0'} + hasBin: true + peerDependencies: + typescript: 4.0.x || 4.1.x || 4.2.x || 4.3.x || 4.4.x || 4.5.x + dependencies: + glob: 7.2.0 + lunr: 2.3.9 + marked: 3.0.8 + minimatch: 3.0.4 + shiki: 0.9.15 + typescript: 4.5.4 + dev: true + /typescript/4.5.4: resolution: {integrity: sha512-VgYs2A2QIRuGphtzFV7aQJduJ2gyfTljngLzjpfW9FoYZF6xuw1W0vW9ghCKLfcWrCFxK81CSGRAvS1pn4fIUg==} engines: {node: '>=4.2.0'} @@ -8555,6 +8780,14 @@ packages: engines: {node: '>= 0.8'} dev: false + /vscode-oniguruma/1.6.1: + resolution: {integrity: sha512-vc4WhSIaVpgJ0jJIejjYxPvURJavX6QG41vu0mGhqywMkQqulezEqEQ3cO3gc8GvcOpX6ycmKGqRoROEMBNXTQ==} + dev: true + + /vscode-textmate/5.2.0: + resolution: {integrity: sha512-Uw5ooOQxRASHgu6C7GVvUxisKXfSgW4oFlO+aa+PAkgmH89O3CXxEEzNRNtHSqtXFTl0nAC1uYj0GMSH27uwtQ==} + dev: true + /w3c-hr-time/1.0.2: resolution: {integrity: sha512-z8P5DvDNjKDoFIHK7q8r8lackT6l+jo/Ye3HOle7l9nICP9lf1Ci25fy9vHd0JOWewkIFzXIEig3TdKT7JQ5fQ==} dependencies: