应用背景
前端文档生成跟随项目代码仓库，无需再去找文档，便与开发者之间快速了解项目情况，参与开发，减少沟通成本和项目接触成本
主要解决三个问题：
- 自注释代码 文档的生成
- 自定义文档生成，和注释文档合成为书的形式
- 文档的发布，查阅，和搜索
涉及相关的技术
技术栈:
- typedoc / jsdoc 用于typescript,javascript 文档注释 自动生成
- gitbook 文档归纳，生成书，在线/离线部署，预览和搜索
- typora(可选) 用于markdown 文件的可视化编写
所需环境：
- node
- nvm（可选） 一个用于切换node 环境的 软件，便于不同项目间 node版本的切换
文档的生成
原理：
想办法生成文档并且转换成 *.md格式的文件,按照 gitbook 的生成要求，
由全部的md文件，组合成特定的目录结构，
生成发布可供浏览，搜索的 web静态文档页面
生成可浏览文档的常用方式
1. typedoc 自动生成（SDK typescript 注释文档自动生成）
直接用 typedoc ,主要用于 typescript 编写的程序，根据严格的代码注释规范，自动生成项目代码文档
typcdoc 安装
npm install typedoc --save-dev
安装完了，注意需要验证，是否安装完可用
npx typedoc --version
出现显示typedoc 版本 号，以及所用当前项目typescript 版本号，则可用
TypeDoc 0.20.0Using TypeScript 4.1.2 from /home/gerrit/typedoc/node_modules/typescript/lib
没有则还需要安装 对应的 typescript 依赖
更详细的安装 教程 官网
注释文档生成
按照 typedoc 注释规则，进行项目 中的对应代码 注释
例如：
/**
* 人实体类
*
* 定义了一个人的属性和方法
*/
export class Person {
public name!: string
private _sex!: string
constructor(name?: string, sex?: string) {
if(name)this.name = name
if(sex)this._sex = sex
}
set sex(sex:string){
this._sex =sex
}
get sex():string{
return this._sex
}
/**
* 获取名字
* @returns {string} 名字
*/
getName(): string {
return this.name
}
/**
* 设置名字
* @param {string} name 要设置的名称
*/
setName(name: string): void {
this.name = name
}
}更详细 typedoc 注释文档
代码注释完，我们便可以自动生成 注释文档，但是生成前，我们需要配置 要自动生成的文件，以及输出目录
在项目根目录，创建 typedoc.json 配置文件
主要需要配置两个属性
- out
输出路径 ，所有文档文件的输出根路径 - entryPoints
入口点，其实就是配置模块入口文件，比如常用的 Index.ts, main.ts，根据入口文件中的 import 去自动寻找模块依赖的所有ts文件.
针对相对独立的模块，就配多个入口文件（手动配置，恐怖如斯，据说 gulp-typedoc 插件可以解决，但是我试踩了很多坑，还是没成功 >.<），本次直接手敲。。。
用 gulp-typedoc 生成md，则需要安装 gulp ，gulp-typedoc,typedoc-plugin-markdown 插件，运行命令
npm install –save-dev gulp-typedoc typedoc typedoc-plugin-markdown
gulp-typedoc 若成功运行的话，会生成 md文件，目录结构类似这样
生成md文件之后组合成 gitbook 要配置的 SUMMARY.md 目录内容，走gitbook流程
可以配合 gitbook 的 自动生成目录插件 summary 来自动 生成summary.md文件内容，之后根据自己需要，修改内容
插件配置 book.json
{
"plugins": ["summary", "toggle-chapters"]
}
插件安装:
gitbook install
安装和配置好 gitbook 直接
gitbook serve
即可看到效果
本次实例走手敲 entryPoints
示例：
{
"out": "docs/typedocview",
"entryPoints": ["src/sdk/DemoSDK.ts","src/sdk/model/Model.ts","src/sdk/model/Animate.ts","src/sdk/model/Person.ts","src/sdk/model/ModelEntity.ts",
"src/sdk/controller/Controller.ts","src/sdk/controller/ModelController.ts","src/sdk/controller/SceneCroller.ts","src/sdk/core.ts","src/sdk/struct/Struct.ts",
"src/sdk/interface/ISDK.ts"
]
}当然也可以在你的 tsconfig.json typescript 编译配置文件中配置,一级节点上加这个配置选项
"typedocOptions": {
"out": "docs/typedoc",
"entryPoints": ["src/sdk/DemoSDK.ts"]
}此时示例目录：
在 package.json 中我的scripts 项，我们加个文档生成命令
"scripts": {
"typedocview": "typedoc ",
},运行 文档生成命令
npm run typedocview
在项目目录 docs/typedocview 会生成 直接可以部署的静态 api文档 网页 文件
直接静态服务器 运行起来，效果如下
2. jsdoc 自动生成 (SDK javascript 注释文档生成)
直接用 jsdoc,由 javascript 编写的程序，根据严格的代码注释规范，自动生成项目代码文档
js 版本的文档也是同 typedoc 类似一样的生成
jsdoc 官网地址
3. gitbook （综合文档）
原理：
由代码注释自动生成的 *.md 文档文件，以及自定义编写的 *.md 文档文件，
根据gitbook要求的文档目录格式，自定义配置 SUMMARY.md 文件，
生成gitbook形式的代码文档，
背景：
由 typedoc 或 jsdoc 生成的文档，往往还不能满足我们的 文档浏览需求，所以我们会综合自动生成文档，结合自定义编写的文档，形成gitbook形式，进行发布
gitbook 的安装
全局安装，便于随处可用
npm install gitbook-cli -g
安装完验证 是否可用
npm gitbook -V
显示对应的版本 gitbook 版本，以及 gitbook -cli 版本，即正确安装
TIPS:
- 建议本地安装，npm install –save-dev gitbook-cli
跟随项目走，不会造成 npm 环境污染 - 注意 node 版本不要太高，否则gitbook build ，gitbook serve 的时候会报错，
造成的原因就是 node 版本太高
比如14.12.0 版本 TypeError: cb.apply is not a function
本次 node 环境 v12.16.3 测试通过
gitbook 初始化
安装成功后，切换到你想要生成文档的目录路径下,本例子在项目根目录的 docs/gitbookdoc 下
cd docs/gitbookdoc gitbook init
运行成功后将自动 创建两个默认的 md 文件
- README.md
readme 介绍 文件，也是gitbook 的主页显示文件 - SUMMARY.md 目录文件
gitbook 文档生成和浏览
生成
gitbook build
实时开发和浏览
gitbook serve
直接会生成 _book 目录，和运行静态网页 默认为 http://localhost:4000
运行效果
gitbook 目录规则 与 book 配置
目录
gitbook 的目录文件配置文件 SUMMARY.md ,里面的内容对应着右边的目录导航
目录规则：
- 一条 markdow 列表对应一个目录
- 列表的层级代表目录的层级
- 列表的链接 *.md 文件 对应着 目录所要表达的章节内容
- [ ] 中括号内的内容为目录内容
示例：SUMMARY.md
* [动物](README.md)
* [猫 ](api/api.md)
* [狗 ](api/api.md)
* [牛 ](api/api.md)
* [机器](controller/index.md)
* [飞机](controller/CameraController.md)
* [坦克]](controller/SceneController.md)
* [航空母舰](controller/ModelController.md)
* [一级目录](路径/xx/x.md)
* [二级目录](路径/x/x.md)
* [二级目录](路径/x/xx.md)
* [三级目录](路径/x/xx.md)
* [三级目录](路径/x/xx.md)
* [二级目录](路径/x/xx.md)
gitbook serve 运行 效果
book 配置
book.json 是针对发布浏览的 静态文档的网页 配置，可以配置插件，各种其他组件等
其中的 plugins 选项就是用来配置插件的，配置完之后，需要安装一下
安装命令
gitbook install
常用的一些插件 资料说明
一个写的不错，更加具体的小伙伴 页面
本次通过typedoc 自动生成的md文件，结合 gitbook 的目录配置规则，配置如下目录
# 介绍
* [Introduction](README.md)
# SDK 文档注释
* 模块
- [DemoSDK](modules/demosdk.md)
- [controller/Controller](modules/controller_controller.md)
- [controller/ModelController](modules/controller_modelcontroller.md)
- [controller/SceneCroller](modules/controller_scenecroller.md)
- [interface/ISDK](modules/interface_isdk.md)
- [model/Animate](modules/model_animate.md)
- [model/Model](modules/model_model.md)
- [model/ModelEntity](modules/model_modelentity.md)
- [model/Person](modules/model_person.md)
- [struct/Struct](modules/struct_struct.md)
* 类
- [Controller](classes/controller_controller.controller)
- [Modelcontroller](classes/controller_modelcontroller.modelcontroller.md)
- [Scenecroller](classes/controller_scenecroller.scenecroller.md)
- [Demosdk](classes/demosdk.demosdk-1.md)
- [Animate](classes/model_animate.animate.md)
- [Model](classes/model_model.model.md)
- [Modelentity](classes/model_modelentity.modelentity.md)
- [Person](classes/model_person.person.md)
- [Struct](classes/struct_struct.struct.md)
* 接口
- [ISDK](interfaces/interface_isdk.isdk.md)
# 自定义文档
* 基础
- [安装](customdoc/base/install.md)
- [应用&组件实例](customdoc/base/instance.md)
- [介绍](customdoc/base/introduction.md)
* 深入组件
- [属性](customdoc/component/component-props.md)
- [组件注册](customdoc/component/component-registration.md)
* 过渡动画
- [过渡动画概述](customdoc/animate/transitions-overview.md)
- [进入过渡￥离开过渡](customdoc/animate/transitions-enterleave.md)
生成的整个文档文件目录
运行gitbook
gitbook serve
查看效果：
相应文件 下载
4. vuepress （偏技术类综合文档，vue官网风格）
可以综合 由代码注释自动生成的 *.md 文档文件，以及自定义编写的 *.md 文档文件，根据vuepress目录格式，配置Config.js 配置文件，生成静态文档页面
vuepress 需要的环境
- vue vue的版本在 2.6.x
- node
vuepress 安装和初始化
vuepress 的目录配置
目录规则
