TypeDoc: 一款TypeScript项目文档生成器

TypeDoc

【TypeDoc：一款 TypeScript 项目文档生成器】

本文简要介绍了 TypeDoc 的安装、使用以及部分配置项信息。

1. TypeDoc概述

TypeDoc 是什么以及它能做什么？

• TypeDoc 是 TypeScript 项目的文档生成器。
• TypeDoc 可以根据 TypeScript 源代码中的注释生成对应的 HTML 文档或 JSON 模型。它是可扩展的并且支持多种配置。可作为 CLI 或节点模块使用。

点击跳转 TypeDoc 主页

---

2. TypeDoc安装及使用

2.1. 前置条件

在进行 TypeDoc 安装之前，需要本地已安装 NPM 客户端。

在终端或CMD窗口运行 npm -v 命令检查本地是否已安装 NPM 客户端，如果未安装，请先安装 NPM 客户端。

2.2. TypeDoc安装

如果 NPM 客户端已安装，则在终端运行以下命令安装 TypeDoc 。

npm i typedoc -D

命令行中加入的 -D 选项，是因为此依赖是在开发环境中使用的，命令执行完毕后依赖项会出现在 package.json 文件的 devDependencies 中。如果是生产环境需要此依赖，则需要移除 -D 选项或者将其改为 -P 。

2.3. TypeDoc使用

CLI既可以从终端使用，也可以从 NPM 脚本使用。

2.3.1 命令使用

typedoc options

其中 options 需要替换成具体的配置项。

2.3.2 使用NPM脚本

在项目的 package.json 的 scripts 项中增加如下命令配置：

"doc": "typedoc --options ./typedoc.json",

2.3.3 配置项加载方式

配置项加载有如下两种方式：

1. 将配置项放置在命令行
2. 将配置项放入配置文件，通过加载配置文件的方式加载配置项【推荐】

注意： 在命令行上的配置项将会覆盖配置文件中设置的配置项。

两种方式具体使用如下：

方式1：将配置项放置在命令行

示例：设置文档的输出目录和项目入口点

typedoc --out docs src/index.ts

当配置项较多时，命令过长，可以将配置项放入配置文件中，通过加载配置文件的方式加载配置项。

方式2：将配置项放入配置文件【推荐】

将配置项信息放入配置文件，typedoc 命令执行时加载配置文件的方式有两种：

1. 使用 --options 标记加载独立的配置文件
2. 使用 --tsconfig 标记加载 tsconfig.json 文件的 typedocOptions 选项配置

下面具体介绍一下这两种方法的使用。

• 第一种：使用--options标记加载独立的配置文件

typedoc --options filename

上述命令中，filename 为配置文件名称，该配置文件是一个 json 选项文件。在命令执行时，会自动加载配置文件，如果没有指定配置文件，TypeDoc 将查找当前目录下的 typedoc.json and typedoc.js文件。

typedoc.json配置文件示例

下面是配置文件中部分配置项示例：

{
  "entryPoints": ["index.ts"],
  "includes": ["src/*.ts"],
  "out": "docs",
  "readme": "none",
  "includeVersion": true,
  "disableSources": false
}

• entryPoints：设置入口点。
• includes：指定一个目录，其中包含可以在文档注释中使用[[include:file.md]]插入到生成文档中的文件。
• out：指定生成的文档的输出位置。
• readme：是否在index页面展示README文件，该属性值设置为 none 时，index页面直接显示API文档内容。
• includeVersion：是否将包的版本号添加到API文档中，默认值为 false。
• disableSources：是否禁用反射源，默认为 false，会在API文档页面出现类似 Defined in src/ArrayUtils.ts:15 的字样，如果不想在页面上显示API对应的文件源信息，可以将此属性值设置为true。

更多配置项信息请查看文后列举的 TypeDoc配置项 或者根据需要自行查阅官方文档。

TypeDoc Options： http://typedoc.org/guides/options/

• 第二种：使用--tsconfig标记加载tsconfig.json文件的typedocOptions选项配置

tsconfig.json 配置文件示例，在 tsconfig.json 文件中可以使用 typedocOptions 部分将配置项定义为 json 模型。

{
    "compilerOptions": {
        "normalTypeScriptOptions": "here"
    },
    "typedocOptions": {
        "entryPoints": ["src/index.ts"],
        "out": "docs"
    }
}

配置完成后，命令行执行 npm run doc，命令成功执行后即可在配置的目录下生成HTML文档。

3. TypeDoc配置项

TypeDoc 接受 TypeScript 编译器接受的大多数命令行参数。所有传入的没有标志的命令行参数都将被解析为输入文件。在命令行上传递的任何选项都将覆盖配置文件中设置的选项。

typedoc [--options]

---

3.1. TypeDoc配置项加载方式

TypeDoc 命令配置项信息可以放在三个地方：

1. 命令行
2. 放在typedoc.json文件中，使用--options选项加载文件
3. 放在tsconfig.json文件的typedocOptions属性中，使用--tsconfig选项加载

3.2. 配置项信息

• options

typedoc --options <filename>

指定应加载的json选项文件。如果没有指定，TypeDoc将在当前目录中查找 typedoc.json 和 typedoc.js文件。json文件应该返回一个对象，其键是选项名。例如：

{
    "entryPoints": ["./src/index.ts", "./src/secondary-entry.ts"],
    "out": "doc"
}

示例：请参考 TypeDoc配置项示例

---

• tsconfig

typedoc --tsconfig </path/to/tsconfig.json>

指定应该被加载的 tsconfig.json 文件。如果没有指定，TypeDoc 将会在当前目录和父目录中查找 tsconfig.json 。

当TypeDoc 加载 tsconfig.json 时，它会读取 typedocOptions 键下的 TypeDoc 选项。

---

• entryPoints

指定要由 TypeDoc 记录的入口点。TypeDoc 将检查这些文件的导出，并根据这些导出创建文档。入口点可以通过三种方式进行处理，详情请参阅--entryPointStrategy 。

示例：请参考 TypeDoc配置项示例

---

• entryPointStrategy

该配置项有三个选择：

• resolve（默认值）

  期望所有的入口点都包含在根级别的 tsconfig 项目中。如果给定了目录，则将 directory/index作为入口点。

• expand

  期望所有的入口点都被包含在根级别的 tsconfig 项目中。如果给定了目录，则其中的文件将递归展开。这个在 V0.21 版本中是默认行为。

• packages

  如果您的代码库由一个或多个npm包组成，您可以将这些路径传递给这些包，TypeDoc将尝试基于package.json中的默认值为index.js的main属性确定入口点，如果没有找到，则基于types属性。如果给定的任何包是一个npm Workspace 或者yarn WorkSpace 的根，TypeDoc 将找到所有的定义在 package.json 中的 workspaces 。

  此模式要求在 JS 入口点中使用 sourcemaps，或者在你的package.json中指定 typedocMain ，来告诉 TypeDoc 入口点 TypeScript 的来源。支持通配符路径，方式与 npm 或 Yarn 工作区中的相同。

关于这三个选择的具体说明请查阅 TypeDoc entryPointStrategy

---

• exclude
  按指定的模式排除文件

---

• includes

typedoc --includes <path/to/includes/>

指定一个目录，其中包含可以在文档注释中使用[[include:file.md]]插入到生成文档中的文件。

示例：请参考 TypeDoc配置项示例

---

• out

typedoc --out <path/to/documentation/>

指定生成的文档的输出位置。

示例：请参考 TypeDoc配置项示例

---

• theme

typedoc --theme default

指定生成的文档使用的主题。

---

• customCss

typedoc --customCss ./theme/style.css

指定一个额外的CSS文件，该文件应复制到assets目录中，并由主题引用。

---

• name

typedoc --name <Documentation title>

设置将要在模版标题中使用的项目的名称。该名称默认为 package.json 中包名和当前版本。

---

• readme

typedoc --readme <path/to/readme|none>

否在index页面展示README文件，该属性值设置为 none 时，index页面直接显示API文档内容。

示例：请参考 TypeDoc配置项示例

---

• includeVersion

是否将包的版本号添加到文档项目名称中，默认值为 false。

如果包名称为Name，版本号为1.2.3，则文档项目名称为Name-v1.2.3

示例：请参考 TypeDoc配置项示例

---

• disableSources

typedoc --disableSources

是否禁用反射源，默认为 false，会在API文档页面出现类似 Defined in src/ArrayUtils.ts:15 的字样，如果不想在页面上显示API对应的文件源信息，可以将此属性值设置为true。

示例：请参考 TypeDoc配置项示例

---

TypeDoc配置项示例

{
  "entryPoints": ["index.ts"],
  "includes": ["src"],
  "out": "docs",
  "readme": "none",
  "includeVersion": true,
  "disableSources": true
}

---

更多更详细的配置项信息使用请移步：http://typedoc.org/guides/options/

---

4. TypeDoc插件

4.1. typedoc-plugin-markdown

该插件结合 TypeDoc 使用，使得生成的文档呈现为 Markdown 形式。

在安装typedoc后再安装此插件。

npm i typedoc-plugin-markdown -D

该插件的使用方法与 TypeDoc 相同。插件使用命令选项除了相关的 TypeDoc 选项外，还可以使用其他的选项。

更多介绍请查看：typedoc-plugin-markdown npmjs

---