Nest 使用 compodoc 生成文档

云牧2024-03-11 23:42

启动 compodoc 文档

compodoc 是一个为 TypeScript 项目生成文档的工具，它支持 Angular、Nest。

compodoc 会分析你的代码，并生成一个包含所有类、接口、服务、控制器和模块以及它们依赖关系的文档。

创建 nest 项目：

bash 复制代码

nest new compodoc-test -p npm

安装 compodoc：

bash 复制代码

npm install @compodoc/compodoc -D

在 package.json 文件的 scripts 部分添加一个新的脚本来运行 compodoc：

json 复制代码

"scripts": {
  "compodoc": "compodoc -p tsconfig.json -s -o",
}

更多选项在 compodoc 文档里可以看到：

生成预览文档：

bash 复制代码

npm run compodoc

自动打开浏览器，并定位到了 README 菜单：

这个 README 菜单其实对应了项目里面的 README：

改一下 READMD.md，然后重新执行命令生成：

文档的 overview 部分分贝是依赖图，和项目有几个模块、controller，可注入的 provider

我们在项目下添加几个模块：

typescript 复制代码

nest g resource test1

nest g resource test2

在 Test1Module 导出 Test1Service：

然后 BbbModule 引入 AaaModule：

在 BbbService 里注入 AaaService：

运行项目：

typescript 复制代码

npm run start:dev

这种依赖关系，compodoc 可视化之后是什么样的呢？

重新跑一下 compodoc：

typescript 复制代码

npm run compodoc

点击左侧的 Modules，可以看到每个模块的可视化分析：

还可以定位到具体代码的实现：

当新人接手这个项目的时候，可以通过这份文档快速了解项目的结构。

命令行选项也挺多的，我们可以写在 compodoc 配置文件中。

项目下添加一个 .compodoc.json 的文件：

json 复制代码

{
    "port": 8888,
    "theme": "postmark"
}

改下 scripts 里 compodoc 命令：

json 复制代码

"scripts": {
   "compodoc": "compodoc -s -o -c .compodoc.json",
 }

-c 参数告诉 compodoc 使用指定的配置文件。

运行：

bash 复制代码

npm run compodoc

同样能使配置生效。