目前我们正在开发一个前端脚手架，由于项目是使用的 Monorepo 来进行开发的，在多包中，我们维护了一个公共函数的包，使其可以提供多个不同的包使用，为了能实现我们编写的工具函数能快速被其他开发者理解到该函数是干什么的，我们可以编写一个开发文档。
如果我额外去编写一个文档的话，可能又需要额外花一点时间，那么这个时候 TypeDoc 就可以派上用场了。
什么是 TypeDoc
TypeDoc 是一个用于 TypeScript 项目的文档生成器。它能够从 TypeScript 源代码中读取注释和类型信息，然后生成详尽的文档。
TypeDoc 的工作原理类似于 Java 的 Javadoc 或 C# 的 XML 文档注释，但它是专门为 TypeScript 设计的。使用 TypeDoc，开发者可以为类、接口、函数等编写注释，然后 TypeDoc 会解析这些注释和 TypeScript 的类型系统，生成静态 HTML 文档。这些文档可以包含代码结构的概览、每个类或函数的详细描述、继承关系、属性和方法的类型信息等。
如何使用 TypeDoc
要使用 TypeDoc，首先需要通过 npm 安装它或者其他包管理工具进行安装。安装完成后，可以在命令行中运行 typedoc 命令，并指定一些参数和你的源代码文件或目录，TypeDoc 就会在指定的输出目录中生成文档。
pnpm add typedoc --save-dev
项目安装完成之后，我们要在 TypeScript 源文件中添加 JSDoc 风格的注释。TypeDoc 会读取这些注释来生成文档。例如：
/**
* 这是一个加法函数。
* @param a 第一个加数
* @param b 第二个加数
* @returns 两个加数的和
*/
function add(a: number, b: number): number {
return a + b;
}
代码编写完成之后，我们可以运行 TypeDoc 命令来生成文档。你可以直接使用 typedoc 命令并指定源代码目录：
npx typedoc --out docs src
这个命令会生成一个 docs 目录（如果尚不存在，则会创建），其中包含你的 TypeScript 项目的文档。src 是你的源代码目录，你应该根据项目实际情况替换它。
最终他会生成这样的文档结构：
当我们打开这个 HTMl 文件的时候，最终结果如下图所示：
但是我们想要的效果还不是这样，最终我们是希望他能够给我们生成一个 md 的文档结构。
如果想将文档输出为 Markdown 格式，可以使用 TypeDoc 的插件系统。首先，安装 Markdown 插件：
pnpm add typedoc-plugin-markdown --save-dev
然后，运行 TypeDoc 并指定使用 Markdown：
npx typedoc --plugin typedoc-plugin-markdown --out docs src
这是它给我们生成的内容，如下图所示：
TypeDoc 配置
TypeDoc 提供了许多选项来定制文档的生成。例如，你可以指定文档的主题、包含或排除特定文件、设置文档的标题等。
{
"out": "docs",
"name": "靓仔",
"entryPoints": ["src/index.ts"],
"theme": "default",
"exclude": ["**/*.test.ts", "**/node_modules/**"],
"tsconfig": "tsconfig.json",
"plugin": ["typedoc-plugin-markdown"],
"readme": "README.md"
}
在上面的这些配置中，我们来讲解一下这几个点：
-
--entryPoints: 指定项目的入口文件或目录。这是生成文档时 TypeDoc 首先查看的 TypeScript 文件。 -
--out: 指定文档输出目录。 -
--name: 为你的文档设置一个标题。 -
--theme: 选择或指定一个主题来改变文档的外观。TypeDoc 支持默认主题，也可以使用第三方主题或自定义主题。 -
--readme: 指定一个 Markdown 文件作为文档的首页内容。 -
--tsconfig: 指定一个 tsconfig.json 文件来告诉 TypeDoc 如何编译你的 TypeScript 项目。 -
--plugin: 加载 TypeDoc 插件。
接下来我们来根据这些内容来生成一个文档，执行如下命令：
npx typedoc
输出结果如下图所示：
README.md 的文件也被我们复制到了文档的首页了，标题也变成了我们设置的靓仔了。
总结
通过遵循以上步骤，你可以为你的 TypeScript 项目生成高质量的文档，帮助团队成员和使用者更好地理解项目的构建和使用方式。
也减少了开发者对文档维护的时间，让其有更多的时间专注在功能开发的方面上。
最后分享两个我的两个开源项目,它们分别是:
如果你该项目感兴趣，可以加入我们获取更多信息，你可以添加我微信 yunmz777，我拉你进群进行交流。
原文链接：https://juejin.cn/post/7355012708582293523 作者：Moment
