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

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

编写你的 stories

在你的 .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 文件夹的路径 node_modules/.cache/ts2doc/doc.json 中生成的 doc.json 文件的内容。

标题

如果你想更新 Doc 的标题，你可以使用 title prop

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

描述

如果你想更新 Doc 的描述，你可以使用 description prop

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

更多示例

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

支持的声明

声明	是否支持
interface	✅
JSDOC	✅
variable	❌
function	❌
type	❌
enum	❌
class	❌
namespace	❌

支持的 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

代码检查 (Lint)

npm run lint

测试

npm test

许可证

根据 MIT 许可证分发。详情请参见 LICENSE 文件。