这是一个具有完整基础设施并且使用 typescript 开发的 javascript 库项目开发模板, 帮助你快速搭建一个自动生成文档的 javascript 工具库.
English | 简体中文
- 开箱即用, 具备完整的基础设施, 无复杂配置
- 使用 typescript 开发, 我们都喜欢 type
- 极快的, 使用 vite 构建, 享受 vite 带来的极速体验
- 注释即文档, 使用 typedoc 以及 typedoc-plugin-markdown自动输出 markdown 文档, 并交给 vitepress 驱动
- 使用 vitest 进行单元测试, 更友好的测试体验, 支持 ui 模式
以下是正在使用这个模板的项目:
- 您可以使用 vitepress-ssg 快速的将项目创建至您的本地
执行创建命令时可以通过选项指定项目名称和模板名称
# npm 7+, 需要额外的双破折号:
npm i vitepress-ssg@latest
# yarn：
yarn add vitepress-ssg my-utils
# pnpm：
pnpm i vitepress-ssg my-utils --template library-complete
### 安装依赖
```sh
cd my-utils
npm install-
开发模式:
这将开启监听模式为将 ts 文件打包至 dist 目录
npm run dev
-
打包生产环境代码
npm run build
-
运行单元测试
npm run test -
运行具有可视化操作界面的单元测试
npm run test:ui
-
运行浏览器环境的 demo
npm run demo:web
-
运行 node 环境的 demo
npm run demo:node
-
开发文档
npm run docs:dev
-
打包文档
npm run docs:build
执行发布命令时, 将使用 release-it 工具发布
npm run release |
npm publish 当执行 npm run docs:dev 时,typedoc 会开启监听模式, 并根据所有导出的方法生成 markdown 文档至 docs/src 目录, 同时 vitepress 开发模式将会启动, 你可以通过http://localhost预览你的文档内容
文档内容还可以在方法的注释中补充, 但是需要注意, 注释内容应该按照 typedoc 规范来编写. 以下是一个示例:
/**
* @name 这是一个说hello的方法
* @group 工具函数
* @param name 名称
* @returns
* @example
* ```ts
* console.log(sayHello('hacxy')); // Hello, hacxy!
* ```
*/
export const sayHello = (name: string): string => {
return `Hello, ${name}!`;
};在这段示例中, 我们丰富了该方法在文档的标题、分组、 参数说明, 以及代码示例, 如果您之前编写过 jsdoc 注释那么应该对此并不会感到陌生, 但是如果您是第一次接触, 请参考 typedoc 来学习如何编写. 另外在注释中我们还可以使用 markdown 语法, 当你使用 markdown 语法时会将 markdown 内容直接渲染至文档中.
上述示例中所用的 tag 作用:
- @name 方法名
- @group 方法所属分组, 这个属性会额外的影响文档的侧边导航栏
- @param 参数说明
- @returns 返回值说明
- @example 代码示例
你不应该去修改 docs/src 目录下的任何文件, 因为这些文件都是通过 typedoc 生成的. 它们最终都会被 vitepress 驱动.
所有模块都应该统一在src/index.ts被导出, 这样 vite 才能找到这个入口为你构建正确的 js 代码, 同时 typedoc 也是通过这个入口来为模块生成文档的.
如果你对此还不是很清楚, 那么可以查看目前正在使用此模板的项目: https://github.com/hacxy/tianjie/blob/main/src/index.ts
typedoc: https://typedoc.org/ typedoc-plugin-markdown: https://typedoc-plugin-markdown.org/docs vite: https://vitejs.dev/ vitepress: https://vitepress.dev/ vitest: https://vitest.dev/