使用compodoc生成文档

使用compodoc工具生成文档

• 全局安装compodoc工具

  npm i -g @compodoc/compodoc
  

• compodoc还依赖于eslint,虽然不安装也没问题。

  npm install eslint --save-dev
  

• 在 package.json 中配置script命令(以下命令按需要修改--language zh-CN配置项 日语:ja-JP)

  "scripts": {
     ...,
      
    "compodoc": "compodoc -p tsconfig.json -d ./compodoc --hideGenerator --theme postmark -w -s --port 8852 --language zh-CN --open",
      
     ...
    },
  

• 开始生成文档

  npm run compodoc 
  

  生成的文档默认在 工程目录下(./compodoc/ )

• 各参数解释

  -h, --help                              输出使用信息
  -V, --version                           输出版本号
  -c, --config [config]                   配置文件:.compodocrc,.compodocrc.json,.compodocrc.yaml或package.json中的compodoc属性
  -p, --tsconfig [config]                 一个tsconfig.json文件
  -d, --output [folder]                   存储生成的文档的位置
  -y, --extraTheme [file]                 外部造型主题
  -n, --name [name]                       文件标题
  -a, --assetsFolder [folder]             外部资产文件夹,用于复制生成的文档文件夹
  -o, --open                              打开生成的文档
  -t, --silent                            在静默模式下,日志消息不会记录在控制台中
  -s, --serve                             提供生成的文档（默认http://localhost:8080/）
  -r, --port [port]                       更改默认服务端口
  -w, --watch                             在serve和force documentation rebuild之后观察源文件
  -e, --exportFormat [format]             以指定格式导出（json,html（默认））
  --language [language]                   用于生成文档的语言（en-US,fr-FR,zh-CN,pt-BR）（默认值:en-US）
  --theme [theme]                         选择一个可用主题,默认为'gitbook'（laravel,original,material,postmark,readthedocs,stripe,vagrant）
  --hideGenerator                         不要在页面底部打印Compodoc徽标
  --toggleMenuItems                       关闭菜单中的默认项目（默认['all']）值:['all']或其中一个['modules','components','directives','classes','injectables','interfaces' , '管道', 'additionalPages']）
  --navTabConfig                          按所需顺序列出导航选项卡对象,其中包含两个字符串属性（“id”和“label”）。双引号必须使用'\'进行转义。可用的选项卡ID是“info”,“readme”,“source”,“templateData”,“tree”和“example”。注意:仅在适用于给定依赖项时才会显示某些选项卡
  --templates [folder]                    Handlebars模板目录的路径,用于覆盖内置模板
  --includes [path]                       要包含的外部markdown文件的路径
  --includesName [name]                   外部降价文件的项目菜单名称（默认“附加文档”）
  --coverageTest                          使用阈值测试文档覆盖率命令（默认为70）
  --coverageMinimumPerFile [minimum]      每个文件的文档覆盖率测试命令至少（默认为0）
  --coverageTestThresholdFail [boolean]   文档覆盖率（全局或每个文件）的测试命令将失败并显示错误或仅警告用户（true:error,false:warn）（默认值:true）
  --coverageTestShowOnlyFailed            仅显示覆盖测试的失败文件
  --unitTestCoverage [json-summary]       要包含单元测试覆盖率,请指定istanbul JSON覆盖率摘要文件
  --disableSourceCode                     不要添加源代码选项卡和源代码链接
  --disableDomTree                        不要添加dom树选项卡
  --disableTemplateTab                    不要添加模板选项卡
  --disableStyleTab                       不要添加样式选项卡
  --disableGraph                          禁用依赖关系图的呈现
  --disableCoverage                       不要添加文档覆盖率报告
  --disablePrivate                        不要在生成的文档中显示私有
  --disableProtected                      不要在生成的文档中显示受保护
  --disableInternal                       不要在生成的文档中显示@internal
  --disableLifeCycleHooks                 不要在生成的文档中显示Angular生命周期钩子
  --disableRoutesGraph                    不要添加路线图
  --disableSearch                         不要添加搜索输入
  --minimal                               只有文档的最小模式。没有搜索,没有图表,没有覆盖。
  --customFavicon [path]                  使用自定义图标
  --customLogo [path]                     使用自定义徽标
  --gaID [id]                             Google Analytics跟踪ID
  --gaSite [site]                         Google Analytics网站名称（默认自动（默认:自动））
  

• 编码注释规范

  编码应参考 jsdoc 规范 ，方法应当写详细的注释。主要有：

  • 注释以单行 /**开头，才会被 compodoc 识别
  • 由于 TypeScript 的定义会自动识别参数类型，jsdoc 风格的参数类型可省略
  • @returns定义返回值的描述
  • @ignore表示忽略该方法或组件的定义，不在文档中生成
  • @link语法可以定义链接另一个方法、文档或外部链接
  • @param定义一个参数的类型和描述
  • @example定义一个示例用法
  • 路由定义：路由定义应指定类型为 Routes(从 @angular/router导入)，以便生成路由树状图
  • 参数：简单的参数，应写明作用，可取值等；复杂参数应使用 Interface定义声明，并标注主要参数的含义

示例：

/**
 * 根组件
 */
@Component({...})
export class AppComponent {
    /**
     * @ignore
     */
    ignoredProperty: string;

    /**
     * @ignore
     */
    @Input() ignoredInput: string;

    /**
     * 属性的注释
     */
    tom: string;

    /**
     * 将传入的字符串参数格式化为数字
     * @param {string} target  该参数具体说明参考 {@link Todo} {@link http://lzw.me/doc/target|target}
     * @returns target 处理后的数字格式
     * @example
     * 一个使用示例如下
     * ```js
     * processTarget('yo')
     * ```
     */
    function processTarget(target:string):number {}
}