generate-ts-docs
v0.0.14
Published
Utilities to parse type information and JSDoc annotations from TypeScript source files, and render Markdown documentation
Downloads
82
Maintainers
Readme
generate-ts-docs
Utilities to parse type information and JSDoc annotations 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
source file:
/**
* 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
script:
import {
parseExportedFunctionsAsync,
renderFunctionDataToMarkdown
} from 'generate-ts-docs'
async function main(): Promise<void> {
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
keyword. It returns an array of FunctionData
objects with the following shape:
[
{
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
will be as follows:
# 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
type FunctionData = {
description: null | string
name: string
parameters: null | Array<ParameterData>
returnType: null | ReturnTypeData
jsDocTags: null | JsDocTagsData
type: string
typeParameters: null | Array<TypeParameterData>
}
type JsDocTagsData = Record<string, null | string>
type ObjectData = {
keys: Array<ParameterData>
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
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<string>
) – 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<Array<FunctionData>>
createCategories(functionsData)
Groups each object in functionsData
by the value of each function’s
tags.category
key.
Parameters
functionsData
(Array<FunctionData>
)
Return type
Array<{
name: string;
functionsData: Array<FunctionData>;
}>
Markdown
renderCategoryToMarkdown(category [, options])
Parameters
category
(object
)name
(string
)functionsData
(Array<FunctionData>
)
options
(object
) – Optional.headerLevel
(number
) – Header level to be used for rendering the category name. Defaults to1
(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 to1
(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<FunctionData>; }>
)
Return type
string
renderFunctionsDataToMarkdownToc(functionsData)
Generate a Markdown table of contents for the given functionsData
.
Parameters
functionsData
(Array<FunctionData>
)
Return type
string
Installation
$ npm install --save-dev generate-ts-docs
Implementation details
The parseExportedFunctionsAsync
function works via the following two-step process:
- Generate type declarations for the given TypeScript source files.
- Traverse and extract relevant information from the AST of the generated type declarations.
(The TypeScript AST Viewer tool is useful for figuring out how nodes should be parsed.)