From 9ad931b5e61038bb12afb80b512c37236bb49584 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sat, 1 Feb 2025 12:03:00 -0500 Subject: [PATCH] feat: use typedocs for new docsite Signed-off-by: aramissennyeydd --- packages/repo-tools/package.json | 1 + packages/repo-tools/src/commands/index.ts | 4 ++ .../src/commands/package-docs/command.ts | 54 +++++++++++++++ typedoc.base.jsonc | 9 +++ yarn.lock | 67 ++++++++++++++++++- 5 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 packages/repo-tools/src/commands/package-docs/command.ts create mode 100644 typedoc.base.jsonc diff --git a/packages/repo-tools/package.json b/packages/repo-tools/package.json index bc9dbe7c47..63682dc484 100644 --- a/packages/repo-tools/package.json +++ b/packages/repo-tools/package.json @@ -81,6 +81,7 @@ "portfinder": "^1.0.32", "tar": "^6.1.12", "ts-morph": "^24.0.0", + "typedoc": "^0.27.6", "yaml-diff-patch": "^2.0.0" }, "devDependencies": { diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts index c298384375..773ba3b024 100644 --- a/packages/repo-tools/src/commands/index.ts +++ b/packages/repo-tools/src/commands/index.ts @@ -262,6 +262,10 @@ export function registerCommands(program: Command) { lazy(() => import('./knip-reports/knip-reports'), 'buildKnipReports'), ); + program + .command('package-docs [paths...]') + .action(lazy(() => import('./package-docs/command'), 'default')); + registerPackageCommand(program); registerRepoCommand(program); registerLintCommand(program); diff --git a/packages/repo-tools/src/commands/package-docs/command.ts b/packages/repo-tools/src/commands/package-docs/command.ts new file mode 100644 index 0000000000..6d39554ef1 --- /dev/null +++ b/packages/repo-tools/src/commands/package-docs/command.ts @@ -0,0 +1,54 @@ +/* + * Copyright 2025 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { exec } from 'child_process'; +import { promisify } from 'util'; +import { paths } from '../../lib/paths'; +import { rm, writeFile } from 'fs/promises'; +import { PackageGraph } from '@backstage/cli-node'; +import path from 'path'; + +const execAsync = promisify(exec); + +export default async function packageDocs() { + const packages = await PackageGraph.listTargetPackages(); + for (const pkg of packages) { + console.log(path.relative(paths.targetRoot, pkg.dir)); + if (path.relative(paths.targetRoot, pkg.dir).startsWith('packages/')) { + continue; + } + const configPath = path.join(pkg.dir, 'typedoc.json'); + try { + const DEFAULT_CONFIG = { + extends: ['../../typedoc.base.jsonc'], + entryPoints: + Object.values(pkg.packageJson.exports ?? {}) ?? pkg.packageJson.main, + }; + await writeFile(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2)); + console.log(`Generating docs for ${pkg.packageJson.name}`); + await execAsync( + `${paths.resolveTargetRoot('node_modules/.bin/typedoc')} --out docs`, + { + cwd: pkg.dir, + }, + ); + } catch (e) { + console.error(`Failed to generate docs for ${pkg.packageJson.name}`); + console.error(e); + } finally { + await rm(configPath); + } + } +} diff --git a/typedoc.base.jsonc b/typedoc.base.jsonc new file mode 100644 index 0000000000..7a4085ec31 --- /dev/null +++ b/typedoc.base.jsonc @@ -0,0 +1,9 @@ +{ + // Note: In TypeDoc 0.26 you can instead specify `packageOptions` if running + // only with packages mode. The separate base config file is retained in this + // example so that individual packages can be built for demonstration of the + // advanced method in the readme. + + "$schema": "https://typedoc.org/schema.json", + "includeVersion": true +} diff --git a/yarn.lock b/yarn.lock index 8b6c025c23..bf00de630b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -8725,6 +8725,7 @@ __metadata: portfinder: ^1.0.32 tar: ^6.1.12 ts-morph: ^24.0.0 + typedoc: ^0.27.6 yaml-diff-patch: ^2.0.0 peerDependencies: "@microsoft/api-extractor-model": "*" @@ -10120,6 +10121,17 @@ __metadata: languageName: node linkType: hard +"@gerrit0/mini-shiki@npm:^1.24.0": + version: 1.27.2 + resolution: "@gerrit0/mini-shiki@npm:1.27.2" + dependencies: + "@shikijs/engine-oniguruma": ^1.27.2 + "@shikijs/types": ^1.27.2 + "@shikijs/vscode-textmate": ^10.0.1 + checksum: aa4a0def0c7c73f2ef49b53f4dab5bf95f8f3b3d2c895baf384d338856a082a6a0487bc87c28d550b7f52ed71cbe98dae7754a5397be52df49a18e75cdd7d087 + languageName: node + linkType: hard + "@gitbeaker/core@npm:^35.8.1": version: 35.8.1 resolution: "@gitbeaker/core@npm:35.8.1" @@ -16547,6 +16559,33 @@ __metadata: languageName: node linkType: hard +"@shikijs/engine-oniguruma@npm:^1.27.2": + version: 1.29.2 + resolution: "@shikijs/engine-oniguruma@npm:1.29.2" + dependencies: + "@shikijs/types": 1.29.2 + "@shikijs/vscode-textmate": ^10.0.1 + checksum: 8713ada50e8875d22d928bd605d509a2c7d5e8c2c8a67b215b169f999457123082a02000182b37b9621903577dae5ac8067c614037fbf0aeb5b6dc2c195e58a2 + languageName: node + linkType: hard + +"@shikijs/types@npm:1.29.2, @shikijs/types@npm:^1.27.2": + version: 1.29.2 + resolution: "@shikijs/types@npm:1.29.2" + dependencies: + "@shikijs/vscode-textmate": ^10.0.1 + "@types/hast": ^3.0.4 + checksum: 3aeb2933b5ceda8afe6e4be624847de5fab392085ddf77fb785cf33014120d1afd6825e666d58895e4c489981196abc161c8a4d2e41f7da33d8f5e83b58cc606 + languageName: node + linkType: hard + +"@shikijs/vscode-textmate@npm:^10.0.1": + version: 10.0.1 + resolution: "@shikijs/vscode-textmate@npm:10.0.1" + checksum: c5a8490417b9439b055844c6c09c3435fc435b1fc3923eb28f05ee346fd68e69df2d93cdaab319a51193970558ff1bf49c5ab047c9ed4fd86c3f9d062457a565 + languageName: node + linkType: hard + "@short.io/opensearch-mock@npm:^0.4.0": version: 0.4.0 resolution: "@short.io/opensearch-mock@npm:0.4.0" @@ -19769,6 +19808,15 @@ __metadata: languageName: node linkType: hard +"@types/hast@npm:^3.0.4": + version: 3.0.4 + resolution: "@types/hast@npm:3.0.4" + dependencies: + "@types/unist": "*" + checksum: 7a973e8d16fcdf3936090fa2280f408fb2b6a4f13b42edeb5fbd614efe042b82eac68e298e556d50f6b4ad585a3a93c353e9c826feccdc77af59de8dd400d044 + languageName: node + linkType: hard + "@types/highlightjs@npm:^10.1.0": version: 10.1.0 resolution: "@types/highlightjs@npm:10.1.0" @@ -45994,6 +46042,23 @@ __metadata: languageName: node linkType: hard +"typedoc@npm:^0.27.6": + version: 0.27.6 + resolution: "typedoc@npm:0.27.6" + dependencies: + "@gerrit0/mini-shiki": ^1.24.0 + lunr: ^2.3.9 + markdown-it: ^14.1.0 + minimatch: ^9.0.5 + yaml: ^2.6.1 + peerDependencies: + typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x + bin: + typedoc: bin/typedoc + checksum: 1a8ac5dd636406fa0bcd4a1e9801d72896256c531c09a56207f991b62b7d4ceb336050a8933a3aba0239da6df5da3436e51c86776043501b6e9483aa0b31e69f + languageName: node + linkType: hard + "types-ramda@npm:^0.30.0": version: 0.30.0 resolution: "types-ramda@npm:0.30.0" @@ -47940,7 +48005,7 @@ __metadata: languageName: node linkType: hard -"yaml@npm:^2.0.0, yaml@npm:^2.0.0-10, yaml@npm:^2.1.1, yaml@npm:^2.2.1, yaml@npm:^2.2.2, yaml@npm:^2.3.2, yaml@npm:^2.3.3, yaml@npm:^2.3.4, yaml@npm:^2.7.0": +"yaml@npm:^2.0.0, yaml@npm:^2.0.0-10, yaml@npm:^2.1.1, yaml@npm:^2.2.1, yaml@npm:^2.2.2, yaml@npm:^2.3.2, yaml@npm:^2.3.3, yaml@npm:^2.3.4, yaml@npm:^2.6.1, yaml@npm:^2.7.0": version: 2.7.0 resolution: "yaml@npm:2.7.0" bin: