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 屬性

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" />;

更多範例

更多範例可以在 examples 資料夾中找到。

支援的宣告

宣告	支援
介面	✅
JSDOC	✅
變數	❌
函式	❌
類型	❌
列舉	❌
類別	❌
命名空間	❌

支援的 JSDoc 標籤

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

路線圖

• 新增對 interface 的支援
• 新增對 JSDoc @type、@link、@default 和 @deprecated 的支援
• 新增對 variable 的支援
• 新增對 enum 的支援
• 新增對 type 的支援
• 新增對 function 的支援
• 新增對 class 的支援
• 新增對 namespace 的支援

如果您有任何建議或想貢獻，請隨時提出問題或 PR。

貢獻

您所做的任何貢獻都非常感謝。

1. Fork 此專案
2. 建立您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的變更 (git commit -m '新增一些 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 檔案。