启动 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",
}
- -p 是指定 tsconfig 文件
- -s 是启动静态服务器
- -o 是打开浏览器
更多选项在 compodoc 文档里可以看到:
生成预览文档:
bash
npm run compodoc
自动打开浏览器,并定位到了 README 菜单:
这个 README 菜单其实对应了项目里面的 README:
改一下 READMD.md,然后重新执行命令生成:
overview
文档的 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 配置文件中。
项目下添加一个 .compodoc.json
的文件:
json
{
"port": 8888,
"theme": "postmark"
}
改下 scripts 里 compodoc 命令:
json
"scripts": {
"compodoc": "compodoc -s -o -c .compodoc.json",
}
-c 参数告诉 compodoc 使用指定的配置文件。
运行:
bash
npm run compodoc
同样能使配置生效。