基于TSDoc规范生成漂亮的开源项目文档

为开源（或私有）项目编写一个漂亮且实用的使用文档，这个要求一点都不过分吧🐶，本文将介绍一套生成项目文档的方案，生成的页面不仅很花瓶，还很能打。

生成的文档页面效果：

手机展示的效果：

重点是：颜值很在线😍，下面介绍该方案主要思路。

主要思路

TSDoc 规范编写源码注释
api-extractor 抽取注释为文档模型
- 使用 tsc 提取类型声明文件 .d.ts
- 解析类型声明文件得到文档模型文件 xxx.api.json
api-documenter 转换文档模型为 markdown 文件 .md
vue-press 编译 markdown 文件为静态网页
- 将上一步生成的 .md 文件放置 vue-press 项目目录中（作为 API 集合）
- 添加自定义页面作为文档的使用指南、特性介绍等
- 按照 vue-press 的说明即可启动预览、编译输出静态页面
- 更换主题、自定义其他配置

关于 TSDoc 的三部曲总结如下：

采用 TSDoc 规范编写代码注释
api-extractor 分析代码注释生成文档模型
api-documenter 解析文档模型生成接口文档

TSDoc 主要包含上面三大步：TSDoc 规范、api-extractor、api-documenter

文档模型也叫做 Doc Model，一般是一个 json 文件：包含了源码中 TSDoc 规范的相关定义

这里是总结的大致思路，你现在看着有点迷糊也没关系，下面将详细讲解。

TSDoc 规范

它是一套适用于 TypeScript 项目的注释规范，按照这个规范写注释可以实现：

在 VSCode 拥有比较好的注释提示
快速地一键生成 API 文档

注释的写法风格和注释提示如下：

VSCode 支持 TSDoc 注释的提示

规范特点

关键的特点在上图中有展示：

@example 表示方法示例代码
@param 定义方法的参数和说明
@public 定义方法为对外导出

更多规范介绍请查看TSDoc文档。

JSDoc

其实，使用大名鼎鼎的 JSDoc 也有上面两大利好，为何不使用 JSDoc？

主要原因是：

JSDoc 主要目的是给 JS 添加类型提示，顺便生成文档，但是该规范非常复杂，写起来很繁琐（需要写大量处理类型相关的注释）；
TSDoc 是微软官方推出的，专门针对 TypeScript 项目，TSDoc 规范非常轻量，不需要额外考虑类型。

更多相关介绍请查看JSDoc文档。

Api-extractor

api-extractor 的作用可简单理解为：提取源码中根据[TSDoc 规范](#TSDoc 规范)编写的注释以及 TS 类型签名。

其主要功能有：

解析源码中代码注释 为文档模型文件 *.api.json*，类似于 babel 对源代码进行解析得到 AST 树；
像 rollup 一样整合 TS 输出的类型声明文件 *.d.ts，可以根据源码中 @public @beta @internal 等标记以及配置规则过滤掉不必要的类型声明；
整合所有对外导出的 API 签名，每次代码变更时将对比新代码的 API 签名与以前的签名是否一致，以此来检查代码变更是否会影响包的对外导出，比如：是否意外的修改了方法名、方法参数数量、误删了对外导出等。

api-extractor 是一个单独的 npm 包，需要单独安装：

bash 复制代码

npm i -D @microsoft/api-extractor

使用之前需要初始化生成配置文件 api-extractor.json

bash 复制代码

npx api-extractor init

然后使用即可，具体用法可查看官方文档

arduino 复制代码

api-extractor run

Api-documenter

api-documenter 的作用可简单理解为：将上一步 api-extractor 提取的文档模型文件转换为便于阅读的 markdown 文件。

api-documenter 是一个单独的 npm 包，需要单独安装：

bash 复制代码

npm i -D @microsoft/api-documenter

转换 *.api.json 文档模型文件为 markdown 文件：

bash 复制代码

npx api-documenter markdown

当然，它还可以输出 DocFx 文件，一般非超大型项目用不上这种格式，感兴趣的可以查看其文档，不赘述了。

Vuepress

Vuepress 的作用可简单理解为：将上一步 api-documenter 生成的 markdown 文件编译为 HTML 页面，相当于化了个美美的妆💅。

安装 vuepress 依赖：

bash 复制代码

npm i -D vuepress

编译生成 HTML 页面：

bash 复制代码

npx vuepress build docs

vuepress 的使用比较简单，可以查看Vuepress官方文档。

Vuepress 主题

Vuepress 生成的 HTML 页面已经是化过妆的，但是不够精美，通过安装不同 Vuepress 主题可以切换不同妆容、服装搭配。

这里推荐三款主题：

vuepress-theme-hope 全家桶（官方加持）
vuepress-theme-antdocs 简洁干净
vuepress-theme-reco 全家桶

Vuepress 分为 1.x 版本和 2.x 版本，主题插件版本要和它保持一致，使用时候需要注意。

下面介绍的示例使用 vuepress@1.x + vuepress-theme-antdocs 。

完整示例

下面写一个完整的 demo 项目，将前文提到的 TSDoc、 vuepress 进行综合使用，也可以去查阅此示例项目源码。

初始化项目

创建一个 TypeScript 项目，目录结构如下：

目录结构平平无奇，src 目录是 TypeScript 项目的源代码，比较重要的配置文件有：

api-extractor.json 是 api-extractor 的配置文件，由下面Api-extractor 配置自动生成；
tsconfig.json 是 TypeScript 的配置文件，配置中必须指定编译时输出类型声明文件 "declaration": true。

Api-extractor 配置

参考官方文档，执行以下命令生成 api-extractor.json 配置文件

bash 复制代码

npx api-extractor init

需要修改 mainEntryPointFilePath 与 tsconfig.json 中指定的类型声明文件输出的路径一致。

这里指定为：<projectFolder>/lib/index.d.ts 相当于 项目根目录/lib/index.d.ts，也就是说：src/index.ts 是我们这个项目的主入口。

配置脚本

编译 TS 生成类型声明文件

bash 复制代码

tsc -p tsconfig.json

编译生成的 JS 和类型声明文件在 lib 目录

提取 TSDoc 注释

bash 复制代码

api-extractor run

会在 dist 目录生成一个合并之后 的类型声明文件，此文件我们用不到，可以通过修改 api-extractor.json 配置关闭这个功能。

在 temp 目录生成的 tsdoc-demo.api.json 是 文档模型文件，后续将用来生成 markdown 文件。

输出 markdown 文件

bash 复制代码

api-documenter markdown -i temp -o docs/api

从 temp 目录读取 文档模型文件 ，生成的 markdown 文件放至 docs/api 目录。

输出静态资源

bash 复制代码

vuepress build docs

将 docs 目录作为 vuepress 的文档入口，会在 docs/.vuepress/dist 目录生成静态 HTML 页面。

需要注意：这里生成的 HTML 页面在 api 文件夹中，访问路径需要带有 api。

整合成 npm 脚本命令

本地启动文档预览，执行：

bash 复制代码

npm run docs:dev

构建生成文档静态页面，执行：

bash 复制代码

npm run docs:build

完善自定义页面

上面只是将源码中注释抽取出来作为项目文档的 API 部分，还需要在 docs 目录下添加一些自定义页面。

自定义页面一般包括：首页、指南等，可以参考 vuepress 官网添自行添加。

首页

首页需定义在文件 docs/index.md 或者 docs/README.md 中，简单配置一些 frontmatter 就有一个比较好看的首页。

frontmatter 是 markdown 文件中添加的一些配置项，使用 --- 符号分隔，可参考其文档

指南

指南页的添加比较自由，按照 vuepress 的要求编写 markdown 文件即可，然后在 docs/.vuepress/config.js 配置中添加导航链接。

配置主题

这里使用 vuepress-theme-antdoc 主题，按照其文档说明添加配置就可以了。

在 docs/.vuepress/config.js 配置中添加配置项：

json 复制代码

{
    theme: 'antdocs',
    themeConfig: {
        nav: [
            { text: '指南', link: '/guide/' },
            { text: 'API', link: '/api/' },
            { text: 'GitHub', link: 'https://github.com/idinofe/xt-core' }
        ]
    }
}

更多的主题配置可以查看主题配置文档。

需要注意：不同的主题配置方式各自有一些不同，选择别的主题时需查阅其配置说明进行配置

最后，你将得到一个漂亮的项目文档页面 🥳 🥳 🥳，效果见文章开头的图片。

总结

本文介绍的方案仅适用于：

基于 TypeScript 的项目
对项目文档外观有讲究

该方案还存在一些待完善功能：

对 API 添加自定义 Tag 标记其开始支持的版本，要求能在生成的网页上显示
当 npm 包出现 major、minor 等大版本更新时，各个版本的 API 都要保留，并提供版本切换的入口

大家如果有补充或者建议，欢迎评论留言一起讨论👋🏼；

另外，我在团队写的一个开源项目中就使用了此方案生成项目文档，可在这里查看效果。

基于TSDoc规范生成漂亮的开源项目文档

主要思路

TSDoc 规范

规范特点

JSDoc

Api-extractor

Api-documenter

Vuepress

Vuepress 主题

完整示例

初始化项目

Api-extractor 配置

配置脚本

编译 TS 生成类型声明文件

提取 TSDoc 注释

输出 markdown 文件

输出静态资源

整合成 npm 脚本命令

完善自定义页面

首页

指南

配置主题

总结

参考资料