Angular自动生成组件文档-基于Compodoc

官方文档

https://compodoc.app/

安装

npm install -g @compodoc/compodoc

项目文件

根目录下创建tsconfig.doc.json文件

{
  "include": ["src/**/*.ts"],
  "exclude": ["src/test.ts", "src/**/*.spec.ts", "src/app/file-to-exclude.ts"]
}

修改根目录下的package.json文件

"scripts": {
  "compodoc": "npx compodoc -p tsconfig.doc.json"
}

启动

在根目录下执行npm run compodoc命令即可

命令执行成功后，会在项目根目录下生成documentation目录，这个就是一个web目录，可以使用web服务器（nginx、apache、http-sever等）打开。

最终效果

在documentation目录使用http-server快速启动一个web服务：

浏览器打开http://127.0.0.1:8080：

在实际项目中，可以看到所有的module、component，component可以看到属性、输入、输出、方法等具体信息。

参数配置

完整参数说明：https://compodoc.app/guides/options.html。

如果命令执行中有关于module相关的报错，如：

[10:57:24] parsing        : D:/webstorm_workspace/jyf-frontend/src/app/routes/routes-routing.module.ts
[10:57:24] Analysing routes definitions and clean them if necessary
Unhandled Rejection at: Promise {
  <rejected> InvalidOperationError: Could not find the node's symbol.
      at Object.throwIfNullOrUndefined (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\node_modules\@ts-morph\common\dist\ts-morph-common.js:473:19)
      at PropertyAccessExpression.getSymbolOrThrow (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\node_modules\ts-morph\dist\ts-morph.js:3054:30)
      at _loop_3 (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:6411:22)
      at RouterParserUtil.cleanFileSpreads (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:6427:17)
      at AngularDependencies.getSourceFileDecorators (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:9320:32)
      at C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:9130:31
      at Array.map (<anonymous>)
      at AngularDependencies.getDependencies (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:9119:21)
      at CliApplication.Application.getDependenciesData (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:10845:40)
      at C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:10656:23
} reason: InvalidOperationError: Could not find the node's symbol.
    at Object.throwIfNullOrUndefined (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\node_modules\@ts-morph\common\dist\ts-morph-common.js:473:19)
    at PropertyAccessExpression.getSymbolOrThrow (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\node_modules\ts-morph\dist\ts-morph.js:3054:30)
    at _loop_3 (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:6411:22)
    at RouterParserUtil.cleanFileSpreads (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:6427:17)
    at AngularDependencies.getSourceFileDecorators (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:9320:32)
    at C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:9130:31
    at Array.map (<anonymous>)
    at AngularDependencies.getDependencies (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:9119:21)
    at CliApplication.Application.getDependenciesData (C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:10845:40)
    at C:\Users\xxxx\AppData\Roaming\npm\node_modules\@compodoc\compodoc\dist\index-cli-298ea115.js:10656:23
[10:57:28] Sorry, but there was a problem during parsing or generation of the documentation. Please fill an issue on github. (https://github.com/compodoc/compodoc/issues/new)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! jiuyi-frontend@0.0.0 compodoc: `npx compodoc -p tsconfig.doc.json --language zh-CN`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the jiuyi-frontend@0.0.0 compodoc script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\xxxx\AppData\Roaming\npm-cache\_logs\2021-12-17T02_57_28_643Z-debug.log

这是Compodoc的一个bug，可以通过增加--disableRoutesGraph参数来禁用RoutesGraph，不过这样最终结果会缺少module的导航（可以通过其它方式迂回实现）。
如果文档只想公布输入和输出，可以通过增加--disableSourceCode来禁用源码显示，属性、方法暂时没有找到对应的参数进行隐藏，可以对生成后的文件进行脚本更新再发布成web服务。