安装

安装环境要求

TypeDoc 需要你的系统上安装了 Node.js 。如果还没装， 请进入 Node.js 官网查看如何安装。

TypeDoc 可以作为 node 软件包进行安装。利用 npm 可以确保所有相应的 依赖包被正确的安装。你可以选择将 TypeDoc 安装到本地项目下，或者 安装到全局环境中。

Note: If you install globally, be aware that npm/cli#7057 means that plugins and themes will get their own installation of TypeDoc unless you use the --legacy-peer-deps flag. This will break many plugins and cause warnings from TypeDoc.

TypeDoc aims to support the two latest TypeScript releases for the latest release. Depending on the scale of breaking changes introduced in a new TypeScript version, a given version may support more versions of TypeScript.

安装

如果你要在某个项目下通过命令行使用 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() {
    // Application.bootstrap also exists, which will not load plugins
    // Also accepts an array of option readers if you want to disable
    // TypeDoc's tsconfig.json/package.json/typedoc.json option readers
    const app = await TypeDoc.Application.bootstrapWithPlugins({
        entryPoints: ["src/index.ts"],
    });

    const project = await app.convert();

    if (project) {
        // 根据实际情况确定输出目录
        const outputDir = "docs";

        // 渲染出的文档
        await app.generateDocs(project, outputDir);
        // 或者输出 JSON 格式数据
        await app.generateJson(project, outputDir + "/documentation.json");
    }
}

main().catch(console.error);