@worktile-devkit/apidoc-template

apidoc template

Usage

Run below command to install @worktile-devkit/apidoc-template

npm install @worktile-devkit/apidoc-template --save-dev

Run below command to generate apo docs use apidoc-template

apidoc -i src/ -o api-docs/ -t node_modules/@worktile-devkit/apidoc-template/src

FAQ

How to generate multilevel grouping(more than 3 levels)?

Add a api notes, define a api name is your next api‘s group name, and define this api name group, then you can generate a 3 levels group, for example:

  /**
    * @apiVersion 1.0.0
    * @api second
    * @apiGroup top
    * @apiName second
    */

  /**
    * @api last
    * @apiGroup second
    * @apiDescription this api note just description how to generate a multilevel grouping
    */

  /**
    * @api last2
    * @apiGroup second
    * @apiDescription this api note just description how to generate a multilevel grouping
    */

then this will generate a 3 levels group, in apidoc-template, will generate:

[{
  name: 'top',
  children: [
    {
      name: 'second',
      group: 'top',
      children: [
        {
          name: 'last1',
          group: 'second',
          description: this api note just description how to generate a multilevel grouping
        },
         {
          name: 'last2',
          group: 'second',
          description: this api note just description how to generate a multilevel grouping
        }
      ]
    }
  ]
}]

How to hide last children api when have multilevel grouping?

First you in your api notes, you should add a @apiHideChildren field, for example:

   /**
     * @apiVersion 1.0.0
     * @api top
     * @apiHideChildren
     * @apiGroup second
     * @apiName top
     * @apiDescription 企业内实际的代码托管平台，例如Github或私有部署的Gitlab。
     */

     /**
       * @api last
       * @apiGroup second
       * @apiDescription this api note just description `hideChildren` field
       */

then you can run below command to generate apo docs use apidoc-template

apidoc -i src/ -o api-docs/ -t node_modules/@worktile-devkit/apidoc-template/src  --parse-parsers apihidechildren=node_modules/@worktile-devkit/apidoc-template/src/parsers/hide-last-children.parse.js

Development

1. Run yarn apidoc will generate api docs with example source (apidoc-template/example)
2. Use browser to open apidoc-template/example-docs/index.html to view running results