@aligov/module-doc

模块文档生成工具

Usage no npm install needed!

<script type="module">
  import aligovModuleDoc from 'https://cdn.skypack.dev/@aligov/module-doc';
</script>

README

module-doc

平台化模块文档生成命令 & 工具，该工具可以将 ts 类型文件解析成 markdown。

安装

npm i @aligov/module-doc -D

以 nodejs 模块使用

const moduleDoc = require('@aligov/module-doc');

或

import moduleDoc from '@aligov/module-doc';

通过命令使用

docgen module --config [config配置json] --files [模块定义文件数组] --deps [模块公共依赖文件数组] --output [输出路径]

config 文件中配置了相关参数可以不用在命令行中输入

config 配置文件样例

配置文件支持 js 或 json 两种不同类型

// js文件
module.exports = {
  files: ["./demo/interfaces/modules/*/*.ts"],
  output: "./output",
  deps: ["./demo/interfaces/interface.ts"],
};


// json文件
{
  "files": [
    "./demo/interfaces/modules/footer/interface_footer.ts",
    "./demo/interfaces/modules/header/interface_header.ts"
  ],
  "output": "./output",
  "deps": ["./demo/interfaces/interface.ts"]
}

类型文件定义说明

ts 类型文件中，需要导出模块信息以IModule_开头，需要导出方法信息以IFun_开头，其他的类型会根据引用分析展示出来。

ts 类型文件如下（详见 demo 目录及 output 生成目录）：

import { ModuleProps } from "../../interface";

export interface A {
  a: string;
  b: number;
}

/**
 * State
 * @description abc
 */
export type State = {
  /**
   * @description       也可以显式加上描述名
   * @default           支持定义默认值
   * @remarks 备注
   */
  title?: string;
  content?: any;
  text: string;
  [propsName: string]: any;
};

export type Action = {
  setReaded: (p: any) => any;
};

/**
 * 模块定义
 * @description 模块组件的参数定义
 */
export default interface IModule_Props extends ModuleProps<State, Action> {
  otherParams: any;
}

/**
 * 模块函数
 * @description 模块方法说明
 * @default xxx
 */
export interface IFun_Fun1 {
  /**
   * @description 参数说明
   * @default abc
   * @remarks xxxx
   */
  param1?: string;
  abc?: string;
  test: number;
}

/**
 * @description 模块方法说明
 * @default xxx
 */
export interface IFun_Fun2 {
  abc?: string;
}


## IModule_Props

> 模块定义


 - description: 模块组件的参数定义

| 属性  | 说明  | 类型  | 默认值 | 必填  | 备注  |
| --- | --- | --- | --- | --- | --- |
| otherParams |  | any |  | 是 |  |
| state | 模块状态 | StateT |  | 是 |  |
| action | 模块动作 | ActionT |  | 是 |  |
| ctx | 全局状态方法透出 | any |  | 否 |  |
| funcs | 模块内部扩展方法 | any |  | 否 |  |
| type | 模块类型 | string |  | 是 |  |
| id | 模块在schema hierarchy 结构中的Id | string |  | 是 |  |

## IFun_Fun1

> 模块函数


 - description: 模块方法说明
 - default: xxx

| 属性  | 说明  | 类型  | 默认值 | 必填  | 备注  |
| --- | --- | --- | --- | --- | --- |
| param1 | 参数说明 | string | abc | 否 | xxxx |
| abc |  | string |  | 否 |  |
| test |  | number |  | 是 |  |

## IFun_Fun2


 - description: 模块方法说明
 - default: xxx

| 属性  | 说明  | 类型  | 默认值 | 必填  | 备注  |
| --- | --- | --- | --- | --- | --- |
| abc |  | string |  | 否 |  |


## State

> State


 - description: abc

| 属性  | 说明  | 类型  | 默认值 | 必填  | 备注  |
| --- | --- | --- | --- | --- | --- |
| title | 也可以显式加上描述名 | string | 支持定义默认值 | 否 | 备注 |
| content |  | any |  | 否 |  |
| text |  | string |  | 是 |  |

## Action



| 属性  | 说明  | 类型  | 默认值 | 必填  | 备注  |
| --- | --- | --- | --- | --- | --- |
| setReaded |  | (p: any) => any |  | 是 |  |

目录说明

tree -I node_modules -L 2

├── README.md           说明文档
├── demo                demo
│   ├── index.js
├── es                  es模块
├── lib                 cjs模块，包含bin命令
│   ├── bin             命令行执行入口
├── output              demo输出文件
├── package.json
├── src                 源码目录
│   ├── bin             命令行执行入口
│   ├── index.ts
│   ├── transformers    ts文件transform解析
│   └── webpack         webpack相关的构建或插件
├── tsconfig.base.json  ts基础配置
├── tsconfig.cjs.json   ts构建cjs配置
└── tsconfig.es.json    ts构建es配置

本地开发

npm start

运行测试

node ./demo/index.js

参考

自动生成 JSX 节点 data-id

用于自动为 JSX 标签生成项目唯一的 key 值。例如用于 css 开放的场景。

docgen dataIdGen [options]

Options:
docgen dataIdGen [options]
      --prettyCig      prettier file config path                        [string]
      --tags           define which jsx tags will be added id. multi tags sholud
                       splited by ','.           [default: "View,Text,div,span"]
      --attributeName  the key will be used as the attribute name
                                                   [string] [default: "data-id"]
      --pattern        the glob file pattern which the files matched will be
                       executed our modify.                             [string]
  • pattern 指定匹配哪些文件，对其做相关操作。若不填，以当前 process.cwd 为 base 查找 jsx|tsx 文件进行操作，请慎重。
  • prettyCig 格式化输出时，可指定 prettier 配置文件，非必填。
  • tags 指定为哪些 JSX 标签进行 data id 生成，非必填。
  • attributeName 指定 data id 的名称，默认为 data-id。