paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 39 Packages Projects Releases Wiki Activity

feat: use typedocs for new docsite

Browse Source 
Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
This commit is contained in:
aramissennyeydd
2025-02-01 12:03:00 -05:00
parent 1a1e6e9eb9
commit 9ad931b5e6
5 changed files with 134 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/repo-tools/package.json
+1
View File
@@ -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": {
packages/repo-tools/src/commands/index.ts
+4
View File
@@ -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);
packages/repo-tools/src/commands/package-docs/command.ts
+54
View File
@@ -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);
}
}
}
typedoc.base.jsonc
+9
View File
@@ -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
}
yarn.lock
+66 -1
View File
@@ -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: