robinson v1.0.21
robinson
a simple web utils building power by edar-cli (skd) Robinson
一个简单的 Web 工具集,采用了现代化的开发工具和流程,包括 TypeScript、ESLint、Jest、Rollup 和 VitePress 等。通过合理的目录结构和配置文件,实现了代码的模块化、测试、文档生成和打包等功能。
downloda https://www.npmjs.com/package/edar-cli
github https://github.com/An-Lijun/Edar-cli
Installation
$ npm i robinson
import {xxx} from 'robinson'
docs
https://an-lijun.github.io/Robinson/
Robinson 项目架构文档
1. 项目概述
Robinson 是一个简单的 Web 工具集,由 edar-cli
构建而成。该项目主要提供一些 Web 开发相关的实用功能,目前仅供内部使用。
2. 项目目录结构
Robinson/
├── .eslintignore
├── .eslintrc.js
├── .gitignore
├── README.md
├── api-extractor.json
├── babel.config.js
├── jest.config.ts
├── package.json
├── pnpm-lock.yaml
├── rollup.config.js
├── tsconfig.json
├── tsdoc-metadata.json
├── plugin/
│ └── index.js
├── vitepress/
│ ├── .vitepress/
│ ├── assets/
│ ├── docsDist/
│ ├── etc/
│ │ ├── docs/
│ │ │ ├── advance.md
│ │ │ └── quick.md
│ │ └── index.md
│ └── temp/
├── .husky/
│ └── pre-commit
├── .vscode/
│ └── settings.json
├── script/
│ ├── docBuild.js
│ ├── genDoc.js
│ ├── publish.js
│ ├── publish2.js
│ └── utils.js
├── src/
│ ├── index.ts
│ └── utils/
└── test/
└── ...
2.1 根目录文件说明
.eslintignore
:指定 ESLint 忽略检查的文件和目录。.eslintrc.js
:ESLint 的配置文件,用于定义代码检查规则。.gitignore
:Git 忽略文件,指定不需要被版本控制的文件和目录。README.md
:项目的说明文档,包含项目的基本信息、安装方法、文档链接等。api-extractor.json
:API 提取工具的配置文件,用于提取项目中的 API 信息。babel.config.js
:Babel 的配置文件,用于进行 JavaScript 代码的转换。jest.config.ts
:Jest 测试框架的配置文件,用于配置测试相关的选项。package.json
:项目的元数据文件,包含项目的依赖、脚本命令等信息。pnpm-lock.yaml
:pnpm 包管理器的锁定文件,记录项目依赖的具体版本信息。rollup.config.js
:Rollup 的配置文件,用于进行模块打包。tsconfig.json
:TypeScript 的配置文件,用于定义 TypeScript 编译器的选项。tsdoc-metadata.json
:TypeScript 文档元数据文件,包含 TypeScript 代码的文档信息。
2.2 文件夹说明
plugin/
:插件相关的代码目录,目前只有一个index.js
文件。vitepress/
:用于构建项目文档的 VitePress 相关目录。.vitepress/
:VitePress 的配置目录。assets/
:文档相关的静态资源目录。docsDist/
:文档构建后的输出目录。etc/
:文档源文件目录,包含advance.md
和quick.md
等文档文件。temp/
:临时文件目录。
.husky/
:Git Hooks 配置目录,包含pre-commit
钩子文件。.vscode/
:VSCode 相关的配置目录,包含settings.json
文件。script/
:项目脚本目录,包含文档构建、发布等相关脚本文件。src/
:项目的源代码目录,包含index.ts
和utils/
目录。test/
:项目的测试代码目录。
脚本
{
"doc": "api-extractor run --config ./config/api-extractor.json --local --verbose ",// 不推荐使用 生成函数json
"doc:trace": "api-extractor run --config ./config/api-extractor.json --local --verbose --traceResolution",//不推荐使用 生成函数md文件
"doc:debug": "api-extractor run --local --verbose --diagnostics && api-documenter markdown -i temp -o vitepress/etc/doc", // 不推荐使用 调试使用
"trace": "tsc dist/types/index.d.ts --traceResolution > trace.log", // 不推荐使用 调试使用
"buildViteDocs": "vitepress build vitepress", // 不推荐使用 打包vitepress 应该使用docs:build命令
"oldupdatelog": "node ./script/updatelog.js", //不推荐使用 生成更新日志md命令 应该使用 updatelog
"pub": "node ./script/publish.js", //不推荐使用 旧版本构建发布函数命令
"prepare": "husky install", // git commit钩子
"test": "jest", //测试命令
"lint": "eslint --fix --ext .js,.vue src",//Eslint格式化命令
"commit": "cz", // 提交命令
"build": "npx rollup -c", //打包函数命令
"genAllDocs": "gulp --gulpfile script/genDoc.js", // 生成全部md文档
"docs:dev": "vitepress dev vitepress", // 开发vitepressDosc使用
"docs:build": "node ./script/docBuild.js", // 打包vitepress
"docs:preview": "vitepress preview", // 预览vitepressDosc使用
"publishRobinson": "node ./script/publish.js", //构建发布函数命令
"genEtc": "api-documenter markdown -i vitepress/temp -o vitepress/etc/doc", //生成函数md文件
"genUpdatelog": "gulp --gulpfile script/updateLogGulp.js", //生成更新日志md命令
"genReport" :"gulp --gulpfile script/report.js", //生成测试报告
}
生成文档
项目提供了文档生成的功能,通过以下命令可以生成文档:
npm run genAllDocs
npm run docs:build
测试
项目使用 Jest 作为测试框架,通过以下命令可以运行测试:
npm run test
3.3 TsType 注释规范
项目中使用了一些自定义的 TsType 注解,包括 @bata
、@description
、@param
、@returns
和 @example
,用于对函数进行描述和注释。
项目代码中使用了特定的注释规范,用于描述函数的相关信息,如:
`@bata`:表示是否为正式版。
`@description`:函数描述。
`@param`:参数说明。
`@returns`:返回值说明。
`@example`:使用示例。
4. 依赖管理
项目使用 pnpm 作为包管理器,pnpm-lock.yaml
文件记录了项目依赖的具体版本信息。主要的依赖包括:
- 开发依赖:ESLint、Babel、Jest、Rollup 等。
- 运行时依赖:一些 Web 开发相关的工具库。
5. 构建与打包
项目使用 Rollup 进行模块打包,通过 rollup.config.js
进行配置。在 package.json
中可以定义打包脚本,例如:
{
"scripts": {
"build": "rollup --config"
}
}
6. 文档编写与展示
项目使用 VitePress 进行文档编写和展示,文档源文件位于 vitepress/etc/docs/src/
目录下,包括 advance.md
和 quick.md
等文件。通过 VitePress 可以将这些 Markdown 文件构建成静态网站。