Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yuanqing/generate-ts-docs
:blue_book: Utilities to parse type information and JSDoc annotations from TypeScript source files, and render Markdown documentation
https://github.com/yuanqing/generate-ts-docs
Last synced: 10 days ago
JSON representation
:blue_book: Utilities to parse type information and JSDoc annotations from TypeScript source files, and render Markdown documentation
- Host: GitHub
- URL: https://github.com/yuanqing/generate-ts-docs
- Owner: yuanqing
- License: mit
- Created: 2020-11-22T09:31:02.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-06-24T01:18:56.000Z (over 1 year ago)
- Last Synced: 2024-09-22T04:10:13.079Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 290 KB
- Stars: 12
- Watchers: 1
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# generate-ts-docs [](https://www.npmjs.com/package/generate-ts-docs) [](https://github.com/yuanqing/generate-ts-docs/actions?query=workflow%3Abuild)
> Utilities to parse type information and [JSDoc annotations](https://jsdoc.app/about-getting-started.html#adding-documentation-comments-to-your-code) from TypeScript source files, and render Markdown documentation
## Usage
First:
```
$ npm install --save-dev generate-ts-docs
```
Suppose that we have the following (highly contrived) toy [`example.ts`](/example/example.ts) source file:
```ts
/**
* Adds two numbers.
*
* @param x First number to add.
* @param y Second number to add.
* @return The sum of `x` and `y`.
*/
export function add(x: number, y: number): number {
return x + y
}
```
…and the following [`generate-ts-docs.ts`](/example/generate-ts-docs.ts) script:
```ts
import {
parseExportedFunctionsAsync,
renderFunctionDataToMarkdown
} from 'generate-ts-docs'
async function main(): Promise {
const functionsData = await parseExportedFunctionsAsync(['./example.ts'])
for (const functionData of functionsData) {
console.log(renderFunctionDataToMarkdown(functionData))
}
}
main()
```
`parseExportedFunctionsAsync` receives an array of globs of TypeScript source files, and parses the functions in these files that have the [`export`](https://www.typescriptlang.org/docs/handbook/modules.html#export) keyword. It returns an array of `FunctionData` objects with the following shape:
```ts
[
{
description: 'Adds two numbers.',
jsDocTags: null,
name: 'add',
parameters: [
{
description: 'First number to add.',
name: 'x',
optional: false,
rest: false,
type: 'number'
},
{
description: 'Second number to add.',
name: 'y',
optional: false,
rest: false,
type: 'number'
}
],
returnType: { description: 'The sum of `x` and `y`.', type: 'number' },
type: 'function',
typeParameters: []
}
]
```
`renderFunctionDataToMarkdown` renders the given array of `FunctionData` objects to a Markdown string.
Now, let’s run the `generate-ts-docs.ts` script, piping its output to a file:
````
$ npm install --dev ts-node
$ node --loader ts-node/esm generate-ts-docs.ts > README.md
````
The output [`README.md`](/example/README.md) will be as follows:
````md
# add(x, y)
Adds two numbers.
***Parameters***
- **`x`** (`number`) – First number to add.
- **`y`** (`number`) – Second number to add.
***Return type***
The sum of `x` and `y`.
```
number
```
````
## API
```ts
type FunctionData = {
description: null | string
name: string
parameters: null | Array
returnType: null | ReturnTypeData
jsDocTags: null | JsDocTagsData
type: string
typeParameters: null | Array
}
type JsDocTagsData = Record
type ObjectData = {
keys: Array
type: 'object'
}
type ParameterData = {
description: null | string
name: string
optional: boolean
rest: boolean
type: string | ObjectData
}
type ReturnTypeData = {
description: null | string
type: string
}
type TypeParameterData = {
name: string
defaultType: null | string
type: null | string
}
```
- [**Functions data**](#functions-data)
- [parseExportedFunctionsAsync(globs [, options])](#parseexportedfunctionsasyncglobs--options)
- [createCategories(functionsData)](#createcategoriesfunctionsdata)
- [**Markdown**](#markdown)
- [renderCategoryToMarkdown(category [, options])](#rendercategorytomarkdowncategory--options)
- [renderFunctionDataToMarkdown(functionData [, options])](#renderfunctiondatatomarkdownfunctiondata--options)
- [**Markdown table of contents**](#markdown-table-of-contents)
- [renderCategoriesToMarkdownToc(categories)](#rendercategoriestomarkdowntoccategories)
- [renderFunctionsDataToMarkdownToc(functionsData)](#renderfunctionsdatatomarkdowntocfunctionsdata)
### Functions data
#### parseExportedFunctionsAsync(globs [, options])
Parses the exported functions defined in the given `globs` of TypeScript
files.
- Functions with the `@ignore` JSDoc tag will be skipped.
- Functions will be sorted in *ascending* order of their `@weight` JSDoc
tag. A function with the `@weight` tag will be ranked *before* a function
without the `@weight` tag.
***Parameters***
- **`globs`** (`Array`) – One or more globs of TypeScript files.
- **`options`** (`object`) – *Optional.*
- **`tsconfigFilePath`** (`string`) – Path to a TypeScript configuration file.
Defaults to `./tsconfig.json`.
***Return type***
```
Promise>
```
#### createCategories(functionsData)
Groups each object in `functionsData` by the value of each function’s
`tags.category` key.
***Parameters***
- **`functionsData`** (`Array`)
***Return type***
```
Array<{
name: string;
functionsData: Array;
}>
```
### Markdown
#### renderCategoryToMarkdown(category [, options])
***Parameters***
- **`category`** (`object`)
- **`name`** (`string`)
- **`functionsData`** (`Array`)
- **`options`** (`object`) – *Optional.*
- **`headerLevel`** (`number`) – Header level to be used for rendering the
category name. Defaults to `1` (ie. `#`).
***Return type***
```
string
```
#### renderFunctionDataToMarkdown(functionData [, options])
***Parameters***
- **`functionData`** (`FunctionData`)
- **`options`** (`object`) – *Optional.*
- **`headerLevel`** (`number`) – Header level to be used for rendering the
function name. Defaults to `1` (ie. `#`).
***Return type***
```
string
```
### Markdown table of contents
#### renderCategoriesToMarkdownToc(categories)
Generate a Markdown table of contents for the given `categories`.
***Parameters***
- **`categories`** (`Array<{ name: string; functionsData: Array; }>`)
***Return type***
```
string
```
#### renderFunctionsDataToMarkdownToc(functionsData)
Generate a Markdown table of contents for the given `functionsData`.
***Parameters***
- **`functionsData`** (`Array`)
***Return type***
```
string
```
## Installation
```
$ npm install --save-dev generate-ts-docs
```
## Implementation details
The [`parseExportedFunctionsAsync`](/src/parse-exported-functions-async.ts) function works via the following two-step process:
1. Generate [type declarations](https://www.typescriptlang.org/docs/handbook/declaration-files/by-example.html) for the given TypeScript source files.
2. Traverse and extract relevant information from the [AST](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API) of the generated type declarations.
(The [TypeScript AST Viewer](https://ts-ast-viewer.com/) tool is useful for figuring out how nodes should be parsed.)
## See also
- [markdown-interpolate](https://github.com/yuanqing/markdown-interpolate)
- [ts-node](https://github.com/TypeStrong/ts-node)
## License
[MIT](/LICENSE.md)