ts2doc

Ts2doc 是一种从 TypeScript 导出的声明（接口、类、函数等）生成文档的工具。

目前它可以作为Storybook 插件使用。

如果您喜欢这个项目，请给它一个星标 ⭐️

安装 Storybook 插件

npm install --save-dev @ts2doc/storybook-addon

示例

从以下 TypeScript 接口显示

/**
 * A movie is a piece of media that is intended to be viewed as a film.
 * @link https://wikipedia.org/wiki/Film | Useful link
 */
export interface Movie extends Media {
    /**
     * The title of the movie
     */
    readonly title: string;
    /**
     * The year the movie was released
     * @type {Date}
     */
    year: number;
    /**
     * The rating of the movie
     * @link https://wikipedia.org/wiki/Film_rating_system Film rating system
     * @default 0
     */
    rating?: number;
    genres: string[];
    /**
     * The actors in the movie
     */
    cast: Actor[];
    /**
     * @deprecated
     */
    director: Director;
}

用法

要显示上面的示例，您需要

设置 Storybook 插件

在您的 main.js 文件中

/* .storybook/main.js */

module.exports = {
    addons: [
        // ... other addons
        {
            name: '@ts2doc/storybook-addon',
            options: {
                patternDocType: 'src/**/*.ts',
                compilerOptions: {} // Optional
            }
        }
    ]
};

patternDocType

用于查找要记录的文件的模式，使用 glob 语法。该模式将从您的项目根目录解析。

compilerOptions

可选。用于解析文件的编译器选项。如果未提供，将使用默认编译器选项。有关更多信息，请参阅 编译器选项。

编写您的故事

在您的 .mdx 文件中，记录 TypeScript 导出的声明

/!\ 它仅适用于 .mdx 文件

/* src/movie.stories.mdx */

import { Meta } from '@storybook/addon-docs';
import { InterfaceDoc } from '@ts2doc/components';
// Always import the doc.json file with the following path
import doc from '.cache/ts2doc/doc.json';

<Meta title="Docs/Interfaces" />

<InterfaceDoc doc={doc.Movie} />

doc 变量是插件在您的 node_modules 文件夹中生成的 doc.json 文件的内容，位于 node_modules/.cache/ts2doc/doc.json。

标题

如果要更新 Doc 的标题，可以使用 title 属性

import { InterfaceDoc } from '@ts2doc/components';
// ...
<InterfaceDoc doc={doc.Movie} title="Movie" />;

描述

如果要更新 Doc 的描述，可以使用 description 属性

import { InterfaceDoc } from '@ts2doc/components';
// ...
<InterfaceDoc doc={doc.Movie} description="Some description" />;

更多示例

更多示例可以在 示例 文件夹中找到。

支持的声明

声明	支持
接口	✅
JSDOC	✅
变量	❌
函数	❌
类型	❌
枚举	❌
类	❌
命名空间	❌

支持的 JSDoc 标签

• @type
• @link
• @default
• @deprecated

路线图

• 添加对 interface 的支持
• 添加对 JSDoc @type、@link、@default 和 @deprecated 的支持
• 添加对 variable 的支持
• 添加对 enum 的支持
• 添加对 type 的支持
• 添加对 function 的支持
• 添加对 class 的支持
• 添加对 namespace 的支持

如果您有任何建议或想贡献，请随时打开一个 issue 或 PR。

贡献

您做出的任何贡献都将受到高度赞赏。

1. Fork 项目
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

开发

安装依赖项

npm ci

构建插件

npm run build

启动 Storybook 应用

npm start

代码风格检查

npm run lint

测试

npm test

许可证

在 MIT 许可证下分发。有关更多信息，请参阅 LICENSE 文件。