安装
安装环境要求
TypeDoc 需要你的系统上安装了 Node.js 。如果还没装, 请进入 Node.js 官网查看如何安装。
TypeDoc 可以作为 node 软件包进行安装。利用 npm
可以确保所有相应的
依赖包被正确的安装。你可以选择将 TypeDoc 安装到本地项目下,或者
安装到全局环境中。
TypeDoc 只支持最新和次新的两个 TypeScript 版本。如果 TypeScript 的新版本引入了较大的不兼容,TypeDoc 才会提供支持更多 TypeScript 版本。
TypeDoc 版本 | TypeScript 版本(们) |
---|---|
0.23 | 4.6 到 4.7 |
0.22 | 4.0 到 4.7 |
0.21 | 4.0 到 4.4 |
0.20 | 3.9 到 4.2 |
0.19 | 3.9 到 4.0 |
安装
如果你要在某个项目下通过命令行使用 TypeDoc,或者调用 TypeDoc 的API,或者在 npm 脚本中使用 TypeDoc 的话,推荐将 TypeDoc 安装到本地。接下来就来安装 TypeDoc 到项目本地:
$ npm install typedoc --save-dev
上述命令执行后会将 TypeDoc 添加到 package.json
文件中的依赖列表中,
其后如论谁执行 npm install
命令都将在为此项目安装相同版本的 TypeDoc。
TypeDoc 的可执行文件名是 typedoc
。要验证其是否有效,可以在项目目录下通过 npx
(npx
是一个和 npm
捆绑在一起的命令行工具) 调用 typedoc,同时向 TypeDoc 传递 --version
参数:
$ npx typedoc --version
TypeDoc 0.23.0
Using TypeScript 4.7.2 from /home/gerrit/typedoc/node_modules/typescript/lib
作为命令行工具使用
命令行工具(CLI)既可以在命令行下使用也可以在 npm 脚本中调用。所有不带 --
标志的参数都将被
解析为入口点(entry points)。通过 --out
或 --json
参数分别指定文档的输出目录和输出格式。
typedoc --out docs src/index.ts
JSON 格式的配置文件
除了在命令行中传递参数,typedoc 命令行工具还支持从 json 文件中读取所有参数。
typedoc.json
从命令行中运行 typedoc 时,你可以将参数定义在名为 typedoc.json
的文件中。
{
// Comments are supported, like tsconfig.json
"entryPoints": ["src/index.ts"],
"out": "docs"
}
tsconfig.json
TypeDoc 的参数也可以定义在 tsconfig.json
文件中。将特定于 TypeDoc 的参数定义到 typedocOptions
键下
即可。
{
"compilerOptions": {
"normalTypeScriptOptions": "here"
},
"typedocOptions": {
"entryPoints": ["src/index.ts"],
"out": "docs"
}
}
作为 Node 模块使用
如果你希望动态配置 TypeDoc 或者脱离命令行来运行 typedoc 的话, 可以作为 node 模块导入(import)并由你自己控制文档的构建。
const TypeDoc = require("typedoc");
async function main() {
const app = new TypeDoc.Application();
// 如果你需要 TypeDoc 加载 tsconfig.json / typedoc.json 文件
app.options.addReader(new TypeDoc.TSConfigReader());
app.options.addReader(new TypeDoc.TypeDocReader());
app.bootstrap({
// 这里是 typedoc 参数
entryPoints: ["src/index.ts"],
});
const project = app.convert();
if (project) {
// 根据实际情况确定输出目录
const outputDir = "docs";
// 渲染出的文档
await app.generateDocs(project, outputDir);
// 或者输出 JSON 格式数据
await app.generateJson(project, outputDir + "/documentation.json");
}
}
main().catch(console.error);