Storybook 插件：JSDoc 到 MDX

描述

此 Storybook 插件会自动扫描您的项目以查找 JavaScript 或 TypeScript 文件，提取 JSDoc 注释并生成全面的 MDX 文档。它与 Storybook 无缝集成，通过直接从您的源代码提取的详细见解和示例来增强您的组件文档。

例如，以下 TypeScript 代码

/**
 * Interface representing a person with an optional age property.
 */
interface Person {
    name: string;
    age?: number;
}

/**
 * Function that prints a person's name and optionally age if provided.
 * @param {Person} person The person.
 */
function printPerson(person: Person): void {
    console.log(`Name: ${person.name}`);
    if (person.age !== undefined) {
        console.log(`Age: ${person.age}`);
    }
}

将在 Storybook 中显示如下

目录

1. 要求
2. 安装
3. 使用方法
4. 配置
5. 特性
6. 未来计划和开发
7. 贡献
8. 许可证
9. 致谢

要求

• Storybook@>=7.0.0

此插件应该适用于任何框架。如果您发现插件无法正常工作，请提交一个问题。

安装

要安装插件，请在您的终端中运行以下命令

npm install storybook-addon-jsdoc-to-mdx --save-dev

或者，如果您更喜欢使用 Yarn

yarn add storybook-addon-jsdoc-to-mdx --dev

使用方法

安装后，将插件添加到您的 .storybook/main.js 配置文件

module.exports = {
  addons: [
    // other addons
    {
      name: 'storybook-addon-jsdoc-to-mdx',
      options: {
        folderPaths: ['./src/'], // paths to folders with JS/TS code
        extensions: ['ts', 'js'] // file extensions to include
      }
    }
  ]
};

配置

插件可以使用以下选项配置

• folderPaths：包含源文件的文件夹路径数组。
• extensions：要包含在文档生成过程中的文件扩展名数组。

特性

• 自动 MDX 生成：将 JSDoc 注释转换为 Storybook 可以显示为文档的 MDX 文件。
• 支持多种文件类型：适用于 JavaScript 和 TypeScript 文件。
• 可自定义的路径和扩展名：您可以指定要包含的目录和文件类型。

未来计划和开发

我一直致力于改进和扩展 Storybook 插件的功能。我正在考虑在未来开发中添加以下一些功能

• 自定义文档模板：允许用户为生成的文档定义自己的模板，从而更好地控制 JS/TS 代码在 Storybook 中的呈现方式。
• AI 驱动的 JSDoc 生成：探索将高级 AI（如大型语言模型）集成到您的代码中以自动生成 JSDoc 注释，从而使文档过程更加无缝。

贡献

欢迎贡献！如果您想贡献，请分叉仓库并使用功能分支。非常欢迎您提交拉取请求。

许可证

此项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE.md 文件。

致谢

• 感谢 Storybook 社区不断提供的支持和灵感。
• 特别感谢所有为使该插件更完善而做出贡献的人。