From 9ad931b5e61038bb12afb80b512c37236bb49584 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sat, 1 Feb 2025 12:03:00 -0500 Subject: [PATCH 1/7] 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: From 73b37c9e95ea228dd40540fec24a727c051a33f5 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Mon, 3 Feb 2025 13:05:51 -0500 Subject: [PATCH 2/7] add more excluded packages Signed-off-by: aramissennyeydd --- .../src/commands/package-docs/command.ts | 66 +++++++++---------- typedoc.json | 26 ++++++++ 2 files changed, 59 insertions(+), 33 deletions(-) create mode 100644 typedoc.json diff --git a/packages/repo-tools/src/commands/package-docs/command.ts b/packages/repo-tools/src/commands/package-docs/command.ts index 6d39554ef1..3fc902ab62 100644 --- a/packages/repo-tools/src/commands/package-docs/command.ts +++ b/packages/repo-tools/src/commands/package-docs/command.ts @@ -13,42 +13,42 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { exec } from 'child_process'; +import { spawn } 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); +const execAsync = promisify(spawn); 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); - } - } + // const packages = await PackageGraph.listTargetPackages(); + // for (const pkg of packages) { + // console.log(path.relative(paths.targetRoot, pkg.dir)); + // 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)); + // } catch (e) { + // console.error(`Failed to generate docs for ${pkg.packageJson.name}`); + // console.error(e); + // } finally { + // } + // } + console.log(`Generating docs.`); + await execAsync( + paths.resolveTargetRoot('node_modules/.bin/typedoc'), + ['--out', 'type-docs', '--entryPointStrategy', 'packages'], + { + stdio: 'inherit', + cwd: paths.targetRoot, + env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=12288' }, + }, + ); + // for (const pkg of packages) { + // const configPath = path.join(pkg.dir, 'typedoc.json'); + // await rm(configPath); + // } } diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000000..e5054a27af --- /dev/null +++ b/typedoc.json @@ -0,0 +1,26 @@ +{ + "entryPoints": ["packages/*", "plugins/*"], + "exclude": [ + "packages/app", + "packages/app-next", + "packages/app-next-example-plugin", + "packages/cli", + "packages/cli-common", + "packages/cli-node", + "packages/e2e-test", + "packages/e2e-test-utils", + "packages/opaque-internal", + "packages/techdocs-cli", + "packages/techdocs-cli-embedded-app", + "packages/yarn-plugin", + "packages/backend" + ], + "packageOptions": { + "exclude": ["**/package.json"], + "includeVersion": true + }, + "name": "Backstage API References", + "entryPointStrategy": "packages", + "includeVersion": false, + "logLevel": "Verbose" +} From 7f089a8649fbde09cccc883a5db5aba758b3827f Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sun, 9 Feb 2025 13:00:42 -0500 Subject: [PATCH 3/7] update to generate + merge as separate steps, runtime down to 40s Signed-off-by: aramissennyeydd --- .gitignore | 5 + .../src/commands/package-docs/command.ts | 188 +++++++++++++++--- .../src/commands/package-docs/utils.ts | 44 ++++ typedoc.json | 26 --- 4 files changed, 205 insertions(+), 58 deletions(-) create mode 100644 packages/repo-tools/src/commands/package-docs/utils.ts delete mode 100644 typedoc.json diff --git a/.gitignore b/.gitignore index 865918c1f7..6627583fce 100644 --- a/.gitignore +++ b/.gitignore @@ -174,3 +174,8 @@ knip.json # Schemathesis temporary files .hypothesis/ .cassettes/ + +# Typedocs temporary files +type-docs +docs.json +tsconfig.typedoc.tmp.json \ No newline at end of file diff --git a/packages/repo-tools/src/commands/package-docs/command.ts b/packages/repo-tools/src/commands/package-docs/command.ts index 3fc902ab62..b9ebfec85c 100644 --- a/packages/repo-tools/src/commands/package-docs/command.ts +++ b/packages/repo-tools/src/commands/package-docs/command.ts @@ -13,42 +13,166 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { spawn } from 'child_process'; +import { exec } from 'child_process'; import { promisify } from 'util'; -import { paths } from '../../lib/paths'; +import { paths as cliPaths, resolvePackagePaths } from '../../lib/paths'; +import { createTemporaryTsConfig } from './utils'; +import { mkdir, readFile, writeFile } from 'fs/promises'; +import pLimit from 'p-limit'; -const execAsync = promisify(spawn); +const limit = pLimit(8); -export default async function packageDocs() { - // const packages = await PackageGraph.listTargetPackages(); - // for (const pkg of packages) { - // console.log(path.relative(paths.targetRoot, pkg.dir)); - // 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)); - // } catch (e) { - // console.error(`Failed to generate docs for ${pkg.packageJson.name}`); - // console.error(e); - // } finally { - // } - // } - console.log(`Generating docs.`); - await execAsync( - paths.resolveTargetRoot('node_modules/.bin/typedoc'), - ['--out', 'type-docs', '--entryPointStrategy', 'packages'], +const execAsync = promisify(exec); + +const EXCLUDE = [ + 'packages/app', + 'packages/app-next', + 'packages/app-next-example-plugin', + 'packages/cli', + 'packages/cli-common', + 'packages/cli-node', + 'packages/e2e-test', + 'packages/e2e-test-utils', + 'packages/opaque-internal', + 'packages/techdocs-cli', + 'packages/techdocs-cli-embedded-app', + 'packages/yarn-plugin', + 'packages/backend', +]; + +const HIGHLIGHT_LANGUAGES = [ + 'ts', + 'tsx', + 'yaml', + 'bash', + 'sh', + 'shell', + 'yml', + 'jsx', + 'diff', + 'js', + 'json', +]; + +function getExports(packageJson: any) { + if (packageJson.exports) { + return Object.values(packageJson.exports).filter( + (e: any) => !(e as string).endsWith('package.json'), + ); + } + return [packageJson.main]; +} + +async function generateDocJson(pkg: string) { + const temporaryTsConfigPath: string = await createTemporaryTsConfig(pkg); + + const packageJson = JSON.parse( + await readFile(cliPaths.resolveTargetRoot(pkg, 'package.json'), 'utf-8'), + ); + + const exports = getExports(packageJson); + if (!exports.length || !exports.some(e => e.startsWith('src'))) { + return; + } + + try { + await mkdir(cliPaths.resolveTargetRoot(`dist-types`, pkg), { + recursive: true, + }); + + const { stdout, stderr } = await execAsync( + [ + cliPaths.resolveTargetRoot('node_modules/.bin/typedoc'), + '--json', + cliPaths.resolveTargetRoot(`dist-types`, pkg, 'docs.json'), + '--tsconfig', + temporaryTsConfigPath, + '--basePath', + cliPaths.targetRoot, + '--skipErrorChecking', + ...(getExports(packageJson).flatMap(e => [ + '--entryPoints', + e, + ]) as string[]), + ].join(' '), + { + cwd: pkg, + env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=12288' }, + }, + ); + console.log(`### Processed ${pkg}`); + console.log(stdout); + console.error(stderr); + } catch (e) { + console.error('Failed to generate docs for', pkg); + console.error(e); + // test + } +} + +export default async function packageDocs(paths: string[] = [], opts: any) { + const selectedPackageDirs = await resolvePackagePaths({ + paths, + include: opts.include, + exclude: opts.exclude, + }); + + console.log(`### Generating docs.`); + await Promise.all( + selectedPackageDirs.map(pkg => + limit(async () => { + if (EXCLUDE.includes(pkg)) { + return; + } + console.log(`### Processing ${pkg}`); + await generateDocJson(pkg); + }), + ), + ); + + const generatedPackageDirs = []; + for (const pkg of selectedPackageDirs) { + try { + const docsJsonPath = cliPaths.resolveTargetRoot( + `dist-types/${pkg}/docs.json`, + ); + const docsJson = JSON.parse(await readFile(docsJsonPath, 'utf-8')); + const index = docsJson.children?.find((child: any) => + child.sources.some((e: any) => e.fileName.endsWith('src/index.ts')), + ); + + if (index) { + index.name = 'index'; + } + await writeFile(docsJsonPath, JSON.stringify(docsJson, null, 2)); + generatedPackageDirs.push(pkg); + } catch (e) { + if (e.code === 'ENOENT') { + console.log('No docs.json found for', pkg); + } else { + throw e; + } + } + } + + const { stdout, stderr } = await execAsync( + [ + cliPaths.resolveTargetRoot('node_modules/.bin/typedoc'), + '--entryPointStrategy', + 'merge', + ...generatedPackageDirs.flatMap(pkg => [ + '--entryPoints', + `dist-types/${pkg}/docs.json`, + ]), + ...HIGHLIGHT_LANGUAGES.flatMap(e => ['--highlightLanguages', e]), + '--out', + cliPaths.resolveTargetRoot('type-docs'), + ].join(' '), { - stdio: 'inherit', - cwd: paths.targetRoot, - env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=12288' }, + cwd: cliPaths.targetRoot, }, ); - // for (const pkg of packages) { - // const configPath = path.join(pkg.dir, 'typedoc.json'); - // await rm(configPath); - // } + + console.log(stdout); + console.error(stderr); } diff --git a/packages/repo-tools/src/commands/package-docs/utils.ts b/packages/repo-tools/src/commands/package-docs/utils.ts new file mode 100644 index 0000000000..2cb95443b6 --- /dev/null +++ b/packages/repo-tools/src/commands/package-docs/utils.ts @@ -0,0 +1,44 @@ +/* + * Copyright 2024 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 fs from 'fs-extra'; +import { paths as cliPaths } from '../../lib/paths'; + +export async function createTemporaryTsConfig(dir: string) { + const path = cliPaths.resolveOwnRoot(dir, 'tsconfig.typedoc.tmp.json'); + + process.once('exit', () => { + fs.removeSync(path); + }); + + let assetTypeFile: string[] = []; + + try { + assetTypeFile = [ + require.resolve('@backstage/cli/asset-types/asset-types.d.ts'), + ]; + } catch { + /** ignore */ + } + + await fs.writeJson(path, { + extends: '../../tsconfig.json', + include: [...assetTypeFile, 'src'], + exclude: [], + }); + + return path; +} diff --git a/typedoc.json b/typedoc.json deleted file mode 100644 index e5054a27af..0000000000 --- a/typedoc.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "entryPoints": ["packages/*", "plugins/*"], - "exclude": [ - "packages/app", - "packages/app-next", - "packages/app-next-example-plugin", - "packages/cli", - "packages/cli-common", - "packages/cli-node", - "packages/e2e-test", - "packages/e2e-test-utils", - "packages/opaque-internal", - "packages/techdocs-cli", - "packages/techdocs-cli-embedded-app", - "packages/yarn-plugin", - "packages/backend" - ], - "packageOptions": { - "exclude": ["**/package.json"], - "includeVersion": true - }, - "name": "Backstage API References", - "entryPointStrategy": "packages", - "includeVersion": false, - "logLevel": "Verbose" -} From 8d480fdea201f8ccb024e18af5c4649298b61bf5 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sun, 9 Feb 2025 13:08:44 -0500 Subject: [PATCH 4/7] clean up Signed-off-by: aramissennyeydd --- packages/repo-tools/src/commands/package-docs/command.ts | 1 - typedoc.base.jsonc | 9 --------- 2 files changed, 10 deletions(-) delete mode 100644 typedoc.base.jsonc diff --git a/packages/repo-tools/src/commands/package-docs/command.ts b/packages/repo-tools/src/commands/package-docs/command.ts index b9ebfec85c..7f6b950b10 100644 --- a/packages/repo-tools/src/commands/package-docs/command.ts +++ b/packages/repo-tools/src/commands/package-docs/command.ts @@ -106,7 +106,6 @@ async function generateDocJson(pkg: string) { } catch (e) { console.error('Failed to generate docs for', pkg); console.error(e); - // test } } diff --git a/typedoc.base.jsonc b/typedoc.base.jsonc deleted file mode 100644 index 7a4085ec31..0000000000 --- a/typedoc.base.jsonc +++ /dev/null @@ -1,9 +0,0 @@ -{ - // 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 -} From b78b2b0ed677e9677dd4ff581bfa0f46c09b0f65 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sun, 9 Feb 2025 13:17:44 -0500 Subject: [PATCH 5/7] add changeset Signed-off-by: aramissennyeydd --- .changeset/six-pugs-hug.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/six-pugs-hug.md diff --git a/.changeset/six-pugs-hug.md b/.changeset/six-pugs-hug.md new file mode 100644 index 0000000000..2f5bddd7f2 --- /dev/null +++ b/.changeset/six-pugs-hug.md @@ -0,0 +1,5 @@ +--- +'@backstage/repo-tools': minor +--- + +Adds a new command `package-docs` to create TypeScript API documentation using TypeDocs. From 9ab0c7ccf060d6778341927dfddd276a51c8145e Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Fri, 14 Feb 2025 10:59:04 -0500 Subject: [PATCH 6/7] move to a peer dep and hide the command Signed-off-by: aramissennyeydd --- package.json | 1 + packages/repo-tools/package.json | 8 ++++++-- packages/repo-tools/src/commands/index.ts | 3 ++- packages/repo-tools/src/commands/package-docs/command.ts | 6 +++++- yarn.lock | 4 ++++ 5 files changed, 18 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index 37ef893865..5444b44e42 100644 --- a/package.json +++ b/package.json @@ -134,6 +134,7 @@ "shx": "^0.3.2", "sloc": "^0.3.1", "sort-package-json": "^2.8.0", + "typedoc": "^0.27.6", "typescript": "~5.2.0" }, "packageManager": "yarn@3.8.1", diff --git a/packages/repo-tools/package.json b/packages/repo-tools/package.json index 63682dc484..a4689c1d82 100644 --- a/packages/repo-tools/package.json +++ b/packages/repo-tools/package.json @@ -81,7 +81,6 @@ "portfinder": "^1.0.32", "tar": "^6.1.12", "ts-morph": "^24.0.0", - "typedoc": "^0.27.6", "yaml-diff-patch": "^2.0.0" }, "devDependencies": { @@ -90,7 +89,8 @@ "@backstage/types": "workspace:^", "@types/is-glob": "^4.0.2", "@types/node": "^20.16.0", - "@types/prettier": "^2.0.0" + "@types/prettier": "^2.0.0", + "typedoc": "^0.27.6" }, "peerDependencies": { "@microsoft/api-extractor-model": "*", @@ -98,11 +98,15 @@ "@microsoft/tsdoc-config": "*", "@useoptic/optic": "^1.0.0", "prettier": "^2.8.1", + "typedoc": "^0.27.0", "typescript": "> 3.0.0" }, "peerDependenciesMeta": { "prettier": { "optional": true + }, + "typedoc": { + "optional": true } } } diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts index 773ba3b024..b737d918bd 100644 --- a/packages/repo-tools/src/commands/index.ts +++ b/packages/repo-tools/src/commands/index.ts @@ -263,7 +263,8 @@ export function registerCommands(program: Command) { ); program - .command('package-docs [paths...]') + .command('package-docs [paths...]', { hidden: true }) + .description('EXPERIMENTAL: Generate package documentation') .action(lazy(() => import('./package-docs/command'), 'default')); registerPackageCommand(program); diff --git a/packages/repo-tools/src/commands/package-docs/command.ts b/packages/repo-tools/src/commands/package-docs/command.ts index 7f6b950b10..8c30b06145 100644 --- a/packages/repo-tools/src/commands/package-docs/command.ts +++ b/packages/repo-tools/src/commands/package-docs/command.ts @@ -71,7 +71,10 @@ async function generateDocJson(pkg: string) { ); const exports = getExports(packageJson); - if (!exports.length || !exports.some(e => e.startsWith('src'))) { + if ( + !exports.length || + !exports.some(e => e.startsWith('src') || e.startsWith('./src')) + ) { return; } @@ -110,6 +113,7 @@ async function generateDocJson(pkg: string) { } export default async function packageDocs(paths: string[] = [], opts: any) { + console.warn('!!! This is an experimental command !!!'); const selectedPackageDirs = await resolvePackagePaths({ paths, include: opts.include, diff --git a/yarn.lock b/yarn.lock index bf00de630b..9f5a98ab5b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -8733,10 +8733,13 @@ __metadata: "@microsoft/tsdoc-config": "*" "@useoptic/optic": ^1.0.0 prettier: ^2.8.1 + typedoc: ^0.27.0 typescript: "> 3.0.0" peerDependenciesMeta: prettier: optional: true + typedoc: + optional: true bin: backstage-repo-tools: bin/backstage-repo-tools languageName: unknown @@ -42812,6 +42815,7 @@ __metadata: shx: ^0.3.2 sloc: ^0.3.1 sort-package-json: ^2.8.0 + typedoc: ^0.27.6 typescript: ~5.2.0 languageName: unknown linkType: soft From f950ce486d9bf683b8074933344d74cb26de07ef Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Fri, 14 Feb 2025 11:04:54 -0500 Subject: [PATCH 7/7] update message Signed-off-by: aramissennyeydd --- .changeset/six-pugs-hug.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/six-pugs-hug.md b/.changeset/six-pugs-hug.md index 2f5bddd7f2..3918942ad3 100644 --- a/.changeset/six-pugs-hug.md +++ b/.changeset/six-pugs-hug.md @@ -2,4 +2,4 @@ '@backstage/repo-tools': minor --- -Adds a new command `package-docs` to create TypeScript API documentation using TypeDocs. +Adds a new experimental hidden command `package-docs` for generating API documentation. This is currently only intended for use in the Backstage main repository.