Skip to content

Commit a894fad

Browse files
committed
fix(docusaurus): bootstrap TypeDoc using API instead of spawnSync to avoid cross-platform issues
1 parent df63e01 commit a894fad

File tree

10 files changed

+548
-933
lines changed

10 files changed

+548
-933
lines changed

.changeset/odd-pants-invite.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'docusaurus-plugin-typedoc': patch
3+
---
4+
5+
- Bootstrap TypeDoc using API instead of spawnSync to avoid cross-platform issues (#762).

package-lock.json

Lines changed: 430 additions & 806 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

packages/docusaurus-plugin-typedoc/package.json

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
"version": "1.2.2",
44
"description": "A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into a Docusaurus project.",
55
"exports": {
6-
".": "./dist/index.js",
7-
"./typedoc": "./dist/plugins/typedoc.js"
6+
".": "./dist/index.js"
87
},
98
"type": "module",
109
"files": [
@@ -24,7 +23,7 @@
2423
},
2524
"scripts": {
2625
"lint": "eslint ./src",
27-
"prebuild": "rm -rf dist && prebuild-options",
26+
"prebuild": "rm -rf dist && copyfiles --up 1 ./src/**/*.cjs ./dist/",
2827
"prepublishOnly": "npm run lint && npm run build",
2928
"build": "tsc",
3029
"pretest": "rm -rf ./test/out && docusaurus generate-typedoc",
@@ -39,7 +38,7 @@
3938
"plugin"
4039
],
4140
"devDependencies": {
42-
"@docusaurus/core": "^3.6.1",
43-
"@docusaurus/types": "^3.6.1"
41+
"@docusaurus/core": "^3.7.0",
42+
"@docusaurus/types": "^3.7.0"
4443
}
4544
}

packages/docusaurus-plugin-typedoc/src/index.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
* @module core
33
*/
44
export { PluginOptions } from './models.js';
5-
export { default } from './plugins/docusaurus.js';
5+
export { default } from './plugin/docusaurus.js';

packages/docusaurus-plugin-typedoc/src/options/declarations.ts

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,6 @@
11
import { DeclarationOption, ParameterType } from 'typedoc';
22
import { DEFAULT_SIDEBAR_OPTIONS } from './options.js';
33

4-
/**
5-
* Used internally to pass options from docusaurus.config to TypeDoc.
6-
*
7-
* @internal
8-
*
9-
* @hidden
10-
*/
11-
export const docusaurusConfigOptions: Partial<DeclarationOption> = {
12-
help: 'docusaurus.config options - should not be used if running as a docusaurus plugin.',
13-
type: ParameterType.String,
14-
defaultValue: '{}',
15-
};
16-
174
/**
185
* **autoConfiguration**
196
*

packages/docusaurus-plugin-typedoc/src/options/options.ts

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,7 @@ export function getPluginOptions(
3535
...opts.sidebar,
3636
},
3737
plugin: [
38-
...new Set([
39-
...['typedoc-plugin-markdown', 'docusaurus-plugin-typedoc/typedoc'],
40-
...(opts.plugin || []),
41-
]),
38+
...new Set([...['typedoc-plugin-markdown'], ...(opts.plugin || [])]),
4239
],
4340
};
4441

packages/docusaurus-plugin-typedoc/src/plugins/docusaurus.ts renamed to packages/docusaurus-plugin-typedoc/src/plugin/docusaurus.ts

Lines changed: 30 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
import { spawnSync } from 'child_process';
21
import * as fs from 'fs';
3-
import * as path from 'path';
2+
import { MarkdownRendererEvent, NavigationItem } from 'typedoc-plugin-markdown';
43
import { PluginOptions } from '../models.js';
54
import { getPluginOptions } from '../options/options.js';
6-
import { presets } from '../options/presets.js';
5+
import { writeSidebar } from './sidebar.js';
76

87
export default async function pluginDocusaurus(
98
context: any,
@@ -35,27 +34,39 @@ export default async function pluginDocusaurus(
3534
* Initiates a new typedoc Application bootstrapped with plugin options
3635
*/
3736
async function generateTypedoc(context: any, opts: Partial<any>) {
37+
// get plugin options
38+
const options = getPluginOptions(context, opts);
39+
3840
// create outDir if it doesn't exist
39-
const outputDir = path.join(context?.siteDir, presets.out);
40-
if (!fs.existsSync(outputDir)) {
41-
fs.mkdirSync(outputDir, { recursive: true });
41+
if (!fs.existsSync(options.out)) {
42+
fs.mkdirSync(options.out, { recursive: true });
4243
}
4344

44-
const { plugin, ...options } = getPluginOptions(context, opts);
45-
46-
// spawn typedoc process and pass docusaurus.config options as a string
45+
// configure options for typedoc
46+
const {
47+
// eslint-disable-next-line @typescript-eslint/no-unused-vars
48+
id,
49+
siteDir,
50+
numberPrefixParser,
51+
docsPresetPath,
52+
sidebar,
53+
...optionsPassedToTypeDoc
54+
} = options;
4755

48-
const typedocExecutable = process.platform === 'win32' ? 'typedoc.cmd' : 'typedoc';
56+
const typeDocApp = await import('./typedoc.cjs');
4957

50-
spawnSync(
51-
typedocExecutable,
52-
[
53-
...plugin.flatMap((plugin) => ['--plugin', plugin]),
54-
'--docusaurusConfigOptions',
55-
`${JSON.stringify(options)}`,
56-
],
57-
{
58-
stdio: 'inherit',
58+
// bootstrap typedoc with options
59+
await typeDocApp.bootstrap(
60+
optionsPassedToTypeDoc,
61+
async (renderer: MarkdownRendererEvent) => {
62+
writeSidebar(
63+
renderer.navigation as NavigationItem[],
64+
renderer.outputDirectory,
65+
sidebar,
66+
siteDir,
67+
docsPresetPath,
68+
numberPrefixParser,
69+
);
5970
},
6071
);
6172
}

packages/docusaurus-plugin-typedoc/src/utils/get-sidebar.ts renamed to packages/docusaurus-plugin-typedoc/src/plugin/sidebar.ts

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,52 @@
1+
import * as fs from 'fs';
2+
import * as path from 'path';
13
import { NavigationItem } from 'typedoc-plugin-markdown';
24
import { Sidebar } from '../types/options.js';
5+
import { adjustBaseDirectory } from '../utils/adjust-basedir.js';
36

4-
export function getSidebar(
7+
export function writeSidebar(
8+
navigation: NavigationItem[],
9+
outputDir: string,
10+
sidebar: Sidebar,
11+
siteDir: string,
12+
docsPresetPath: string,
13+
numberPrefixParser: any,
14+
) {
15+
if (sidebar?.autoConfiguration) {
16+
const sidebarPath = path.resolve(outputDir, 'typedoc-sidebar.cjs');
17+
18+
let baseDir = path
19+
.relative(siteDir, outputDir)
20+
.split(path.sep)
21+
.slice(1)
22+
.join('/');
23+
24+
if (docsPresetPath) {
25+
baseDir = adjustBaseDirectory(baseDir, docsPresetPath);
26+
}
27+
28+
const sidebarJson = getSidebar(
29+
navigation,
30+
baseDir,
31+
sidebar,
32+
numberPrefixParser,
33+
);
34+
35+
fs.writeFileSync(
36+
sidebarPath,
37+
`// @ts-check
38+
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
39+
const typedocSidebar = { items: ${JSON.stringify(
40+
sidebarJson,
41+
null,
42+
sidebar.pretty ? 2 : 0,
43+
)}};
44+
module.exports = typedocSidebar.items;`,
45+
);
46+
}
47+
}
48+
49+
function getSidebar(
550
navigation: NavigationItem[],
651
basePath: string,
752
options: Sidebar,
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
/**
2+
* Export as cjs to be compatible with esm
3+
*/
4+
module.exports = {
5+
bootstrap: async (options, postRenderCallbackFn) => {
6+
const typedoc = await import('typedoc');
7+
8+
const app = await typedoc.Application.bootstrapWithPlugins(options, [
9+
new typedoc.TypeDocReader(),
10+
new typedoc.PackageJsonReader(),
11+
new typedoc.TSConfigReader(),
12+
]);
13+
14+
app.renderer.postRenderAsyncJobs.push(postRenderCallbackFn);
15+
16+
const project = await app.convert();
17+
18+
// if project is undefined typedoc has a problem - error logging will be supplied by typedoc.
19+
if (!project) {
20+
return;
21+
}
22+
23+
if (options.watch) {
24+
app.convertAndWatch(async (project) => {
25+
await app.generateOutputs(project);
26+
});
27+
} else {
28+
await app.generateOutputs(project);
29+
}
30+
},
31+
};

packages/docusaurus-plugin-typedoc/src/plugins/typedoc.ts

Lines changed: 0 additions & 84 deletions
This file was deleted.

0 commit comments

Comments
 (0)