https://github.com/jpiazzal/ts2doc
Parse exported declarations from typescript files into object, for documentation
https://github.com/jpiazzal/ts2doc
documentation hacktoberfest json storybook typescript
Last synced: about 1 year ago
JSON representation
Parse exported declarations from typescript files into object, for documentation
- Host: GitHub
- URL: https://github.com/jpiazzal/ts2doc
- Owner: jpiazzal
- License: mit
- Created: 2022-11-29T09:40:26.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-20T15:27:46.000Z (over 1 year ago)
- Last Synced: 2025-04-21T10:53:41.523Z (about 1 year ago)
- Topics: documentation, hacktoberfest, json, storybook, typescript
- Language: TypeScript
- Homepage:
- Size: 4.69 MB
- Stars: 7
- Watchers: 1
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```sh
npm install --save-dev @ts2doc/storybook-addon
```
## Example
Is displayed from the following TypeScript interface:
```ts
/**
* 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:
```js
/* .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](https://www.npmjs.com/package/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](https://www.typescriptlang.org/docs/handbook/compiler-options.html) for more information.
### Write your stories
In your `.mdx` file, to document a TypeScript exported declaration:
**/!\ It only works with `.mdx` files**
```js
/* 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';
```
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:
```js
import { InterfaceDoc } from '@ts2doc/components';
// ...
;
```
**Description:**
If you want to update the description of the `Doc`, you can use the `description` prop:
```js
import { InterfaceDoc } from '@ts2doc/components';
// ...
;
```
## More examples
More examples can be found in the [examples](examples/storybook-app/) folder.
## Supported declarations
| Declaration | Supported |
| ----------- | --------- |
| `interface` | ✅ |
| `JSDOC` | ✅ |
| `variable` | ❌ |
| `function` | ❌ |
| `type` | ❌ |
| `enum` | ❌ |
| `class` | ❌ |
| `namespace` | ❌ |
JSDoc tags supported:
- `@type`
- `@link`
- `@default`
- `@deprecated`
## Roadmap
- [x] Add support for `interface`
- [x] 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.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## Development
### Install dependencies
```sh
npm ci
```
### Build addon
```sh
npm run build
```
### Start storybook app
```sh
npm start
```
### Lint
```sh
npm run lint
```
### Test
```sh
npm test
```
## License
Distributed under the `MIT` License. See `LICENSE` file for more information.