close
Rspress
  • 中文

      • @rspress/plugin-typedoc
      源码

      集成 TypeDoc 的 Rspress 插件，用于自动生成 TS 模块的 API 文档。

      安装

      npm
      yarn
      pnpm
      bun
      deno
      npm add @rspress/plugin-typedoc -D

      使用

      import { defineConfig } from '@rspress/core';
import { pluginTypeDoc } from '@rspress/plugin-typedoc';
import path from 'path';

export default defineConfig({
  plugins: [
    pluginTypeDoc({
      entryPoints: [
        path.join(__dirname, 'src', 'foo.ts'),
        path.join(__dirname, 'src', 'bar.ts'),
      ],
    }),
  ],
});
      src/foo.ts
      /**
 * 这是一个add函数
 */
export function add(
  /**
   * This is param1
   */
  param1: string,
  /**
   * This is param2
   */
  param2: number,
) {
  return 1;
}
      src/bar.ts
      /**
 * This is multi function
 */
export function multi(
  /**
   * This is param1
   */
  param1?: string,
  /**
   * This is param2
   */
  param2?: number,
) {
  return 1;
}

      当你启动项目后，插件会在你的文档根目录下自动生成 api 目录，目录结构如下：

      api
      _meta.json
      index.md
      functions
      bar.multi.md
      foo.add.md
      interfaces
      foo.RunTestsOptions.md
      foo.TestMessage.md
      modules
      bar.md
      foo.md

      也就是说，插件内部会调用 TypeDoc 帮你自动生成模块的 API 文档，包含模块列表、Interface 详情、函数详情(入参、返回值、描述信息) 等信息。

      注意，每次启动项目时都会根据最新的模块内容重新生成 .md 文档。因此，我们建议将 api 目录下的 .md 文件加入 .gitignore 中，例如 docs/api/**/*.md。如果你通过下面的 outDir 参数自定义了输出目录，也应该将相应的 .md 文件加入 .gitignore 中。

      _meta.json 文件只会在首次运行时自动生成，之后不会被覆盖，因此你可以手动编辑它来自定义侧边栏结构（例如添加分隔符、调整顺序等），并将其提交到 git 中。

      我们不建议在 api 目录下修改已生成的 .md 文档，因为随着模块内容的变化，这些文档在每次项目启动时会被覆盖。

      参数说明

      entryPoints

      • 类型：string[]
      • 默认值：[]

      指定需要生成文档的 TS 模块路径，你需要传入模块的绝对路径。

      outDir

      • 类型：string
      • 默认值：api

      自定义文档输出目录，你需要传入一个相对路径，比如 api/custom。

      setup

      • 类型：(app: Application) => Promise<Application> | Promise<void> | void
      • 默认值：() => {}

      用于设置 TypeDoc Application 的函数。你可以使用它在生成文档之前自定义 TypeDoc 配置。