ts2doc
Ts2doc is a tool to generate documentation from TypeScript exported declarations (interfaces, classes, functions, etc.).
For now it can be used as a storybook addon.
If you like this project, please give it a star ⭐️
Install storybook addon
npm install --save-dev @ts2doc/storybook-addon
Example
Is displayed from the following TypeScript interface:
/**
* 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;
}
Usage
To display the example above, you need to:
Setup storybook addon
In your main.js
file:
/* .storybook/main.js */
module.exports = {
addons: [
// ... other addons
{
name: '@ts2doc/storybook-addon',
options: {
patternDocType: 'src/**/*.ts',
compilerOptions: {} // Optional
}
}
]
};
patternDocType:
The pattern to find the files to document, using glob syntax. The pattern will be resolved from your project root.
compilerOptions:
Optional. The compiler options to use to parse the files. If not provided, the default compiler options will be used. See compiler options for more information.
Write your stories
In your .mdx
file, to document a TypeScript exported declaration:
/!\ It only works with .mdx
files
/* 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} />
The doc
variable is the content of the doc.json
file generated by the addon in your node_modules
folder at node_modules/.cache/ts2doc/doc.json
.
Title:
If you want to update the title of the Doc
, you can use the title
prop:
import { InterfaceDoc } from '@ts2doc/components';
// ...
<InterfaceDoc doc={doc.Movie} title="Movie" />;
Description:
If you want to update the description of the Doc
, you can use the description
prop:
import { InterfaceDoc } from '@ts2doc/components';
// ...
<InterfaceDoc doc={doc.Movie} description="Some description" />;
More examples
More examples can be found in the examples folder.
Supported declarations
Declaration | Supported |
---|---|
interface |
✅ |
JSDOC |
✅ |
variable |
❌ |
function |
❌ |
type |
❌ |
enum |
❌ |
class |
❌ |
namespace |
❌ |
JSDoc tags supported:
@type
@link
@default
@deprecated
Roadmap
- Add support for
interface
- Add support for JSDoc
@type
,@link
,@default
and@deprecated
- Add support for
variable
- Add support for
enum
- Add support for
type
- Add support for
function
- Add support for
class
- Add support for
namespace
If you have a suggestion or you want to contribute, feel free to open an issue or a PR.
Contributing
Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Development
Install dependencies
npm ci
Build addon
npm run build
Start storybook app
npm start
Lint
npm run lint
Test
npm test
License
Distributed under the MIT
License. See LICENSE
file for more information.