使用typeDoc快速生成开发文档

部门A采用ReactNative开发,维护RN组件库,部门B采用原生开发。为了应对业务的快速迭代,B部门的学生也需要访问RN。所以就有了以下问题。


B 部门同学想要知道:

  • A 组件库支持什么功能
  • A 组件库的组件怎么使用

A 部门组件库存在的问题:

  • 没有文档说明(曾经有,迭代太快,写文档太麻烦,久而久之就过时了)
  • 注释较少,时间久了,原开发同学都离职了,想要搞清楚组件支持的功能得扒源码看


A需要经常支持B,这很麻烦,不想花太多时间写文档。为了解决这个问题,我参考了原生开发使用的Javadoc工具,最后找到了这个-typedoc。使用后体验还可以,比每次选择源代码都方便。写一篇文章来分享这个工具。


TypeDoc 将 TypeScript 源代码中的注释转换为呈现的 HTML 文档或 JSON 模型。它是可扩展的,支持多种配置。


初始化工程

创建一个新的 TS React 应用来演示功能

npm install -g create-react-app
create-react-app type-doc-demo --template typescript

安装typeDoc

npm install typedoc --save-dev

工程说明

组件工程的目录结构如下所示

.
├── components
│   ├── Card
│   │   └── index.tsx
│   ├── Filter
│   │   └── index.tsx
│   └── index.tsx
├── demo
│   └── Filter.tsx
├── App.tsx
...

components/index.tsx导出所有组件,demo目录包含示例代码。

// components/index.tsx
export { Card } from "./Card";
export type { CardProps } from "./Card";
export { Filter } from "./Filter";
export type { FilterProps } from "./Filter";


基础功能

在项目根目录创建typedoc.js文件,指定入口文件和输出目录

// typedoc.js
module.exports = {
  entryPoints: ["./src/components/index.tsx"],
  out: "doc",
  name: "组件库",
};

package.json添加脚本打包看看效果

// package.json
...
 "scripts": {
    "doc": "typedoc --tsconfig tsconfig.json --options typedoc.js"
  },
...

执行 npm run doc,效果如下,默认会将README.md内容放在首页

使用typeDoc快速生成开发文档

MarkDown语法

typeDoc将通过导出内容的注释生成文档,注释支持MarkDown语法,所以可以将注释这么


插入表格

export type FilterProps = {
    /**
   * 弹窗类型
   *
   * |drop|fullscreen|
   * |:---:|:---:|
   * |下拉| 全屏|
   *  */
  modalMode?: "dorp" | "fullscreen";
};

插入示例代码

export type FilterProps = {
  /**
   * 配置
   * ```
   * {
   *        base_filter: {
   *          checkBox: {
   *            columns: 4,
   *          },
   *        },
   *      }
   *```
   */
  config?: object;
};

生成文档效果

使用typeDoc快速生成开发文档

插入自定义资源

typedoc.js增加如下配置

// typedoc.js
module.exports = {
  ...
  media: ["./demo-images"],
  includes: ["./src/demo"],
};
  • includes: 包含文件的目录,这些文件可以[[include:file.md]]在文档注释中注入到生成的文档中。
  • media:指定将复制到输出文件的媒体目录。媒体可以media://file.jpg在文档注释中链接到


添加上述配置后,在注释中就可以通过如下方式访问对应资源了

/**
 * # 筛选器
 * ## 示例图
 * <img src="media://Filter.jpg"  width="50%" />
 *
 * @see [数据格式说明文档](https://www.baidu.com)
 *
 * ## 代码示例
 * ### 使用
 * ```
 * [[include:Filter.tsx]]
 * ```
 **/
export const Filter: React.FC<FilterProps> = () => {
  ...
};

生成文档效果如下

使用typeDoc快速生成开发文档

综上,便以较小的工作量生成了一个简单的开发文档,提供了代码示例、功能示例图、属性说明,如果只供内部使用的话还比较方便。


其他配置

配置文件


可以在typedoc.js文件中填下如下配置

module.exports = {
  excludePrivate: true,  // 导出不包含private声明内容
  excludeProtected: true, // 导出不包含protected声明内容
  // 将包版本添加到项目名称中。在这种情况下,如果项目是根据 1.2.3 版本`package.json`,这将生成名为“名称 - v1.2.3”的文档
  includeVersion: true, 
};

注释标签

  • @ignore:文档忽略该模块
  • @category:将该内容分组,同标签会划分一起

使用typeDoc快速生成开发文档


上一篇:Android Studio和SDK下载、安装和环境变量配置(全网最全步骤)


下一篇:人工智能Java SDK:人车非识别