Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/peterpeterparker/tsdoc-markdown
Generates markdown documentation from TypeScript source code.
https://github.com/peterpeterparker/tsdoc-markdown
Last synced: 12 days ago
JSON representation
Generates markdown documentation from TypeScript source code.
- Host: GitHub
- URL: https://github.com/peterpeterparker/tsdoc-markdown
- Owner: peterpeterparker
- License: mit
- Created: 2022-08-18T12:32:29.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-30T18:05:28.000Z (13 days ago)
- Last Synced: 2024-10-30T18:28:48.341Z (13 days ago)
- Language: TypeScript
- Homepage:
- Size: 417 KB
- Stars: 45
- Watchers: 1
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tsdoc-markdown
Generates markdown documentation from TypeScript source code. Useful for generating docs from code and injecting automatically the outcome into project README files.
[![npm][npm-badge]][npm-badge-url]
[![license][npm-license]][npm-license-url]
[npm-badge]: https://img.shields.io/npm/v/tsdoc-markdown?style=flat-square
[npm-badge-url]: https://www.npmjs.com/package/tsdoc-markdown
[npm-license]: https://img.shields.io/npm/l/tsdoc-markdown?style=flat-square
[npm-license-url]: https://github.com/buildwithjuno/juno-js/blob/main/LICENSE
[](#contributors-)
## :1234: Table of contents
- [:1234: Table of contents](#1234-table-of-contents)
- [:arrow_down: Installation](#arrow_down-installation)
- [:electric_plug: GitHub Actions](#electric_plug-github-actions)
- [:zap: Usage](#zap-usage)
- [:toolbox: Functions](#toolbox-functions)
- [:gear: buildDocumentation](#gear-builddocumentation)
- [:gear: documentationToMarkdown](#gear-documentationtomarkdown)
- [:gear: generateDocumentation](#gear-generatedocumentation)
- [:books: Useful Resources](#books-useful-resources)
- [:sparkles: Contributors](#sparkles-contributors)
- [:page_facing_up: License](#page_facing_up-license)
## :arrow_down: Installation
Install the library in your project from [npm](https://www.npmjs.com/package/tsdoc-markdown):
```bash
npm install -D tsdoc-markdown
```
## :electric_plug: GitHub Actions
A GitHub Actions workflow that generates the documentation for pull requests using this library is available in [tsdoc.yml](/.github/workflows/tsdoc.yml).
## :zap: Usage
This tool is shipped with a NodeJS [bin](/bin/index.js) script `tsdoc` that can be added to your `package.json`.
e.g. generating the documentation for a source file `./src/index.ts`:
```json
{
"script": {
"tsdoc": "tsdoc --src=src/index.ts"
}
}
```
The `--src` parameter accepts a comma separated list of paths and wildcards as well.
e.g.
```bash
tsdoc --src=src/lib/*
tsdoc --src=src/lib/index.ts,src/lib/docs.ts
```
> Note: the library exports per default only the documentation of the pattern you provide. It does not explore the TypeScript tree. If you wish to do so, either provide a PR to the Cli to support the option `explore` or create your own script for your project 😉
The Markdown documentation is parsed per default in a `./README.md` that finds place where you started the command line.
The output file will be over write unless you specify a `TSDOC_START` and `TSDOC_END` tag (as HTML comment). In such case, the documentation will be parsed within these two tags.
Specifying another output file is also supported with the parameter `--dest`.
To generate links to the documented source code, you can also provide the `--repo` parameter, which corresponds to the URL of your repository on GitHub.
This library generates Markdown documentation from TypeScript source code for `Functions`, `Constants` and `Classes`. Documentation for `Interfaces` and `Types` is not generated by default. To opt-in for types use the parameter `--types`.
Using above script is of course optional. You can also develop your own JavaScript script and use one of the functions here under.
e.g.
```javascript
#!/usr/bin/env node
const {generateDocumentation} = require('tsdoc-markdown');
// Generate documentation for a list of files
const nnsInputFiles = [
'./packages/nns/src/account_identifier.ts',
'./packages/nns/src/genesis_token.canister.ts',
'./packages/nns/src/governance.canister.ts',
'./packages/nns/src/icp.ts'
];
generateDocumentation({
inputFiles: nnsInputFiles,
outputFile: './packages/nns/README.md'
});
// Start from a single file and explore the TypeScript tree
const utilsInputFiles = ['./packages/utils/src/index.ts'];
generateDocumentation({
inputFiles: utilsInputFiles,
outputFile: './packages/utils/YOLO.md',
buildOptions: {
explore: true,
repo: {
url: 'https://github.com/peterpeterparker/tsdoc-markdown'
}
}
});
// Generate documentation for types and interfaces as well
const utilsInputFiles = ['./packages/utils/src/index.ts'];
generateDocumentation({
inputFiles: utilsInputFiles,
outputFile: './packages/utils/YOLO.md',
buildOptions: {
types: true
}
});
```
## :toolbox: Functions
- [buildDocumentation](#gear-builddocumentation)
- [documentationToMarkdown](#gear-documentationtomarkdown)
- [generateDocumentation](#gear-generatedocumentation)
### :gear: buildDocumentation
Build the documentation entries for the selected sources.
| Function | Type |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| `buildDocumentation` | `({ inputFiles, options }: { inputFiles: string[]; options?: BuildOptions or undefined; }) => DocEntry[]` |
Parameters:
- `params.inputFiles`: The list of files to scan and for which the documentation should be build.
- `params.options`: Optional compiler options to generate the docs
[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/lib/docs.ts#L398)
### :gear: documentationToMarkdown
Convert the documentation entries to an opinionated Markdown format.
| Function | Type |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `documentationToMarkdown` | `({ entries, options }: { entries: DocEntry[]; options?: MarkdownOptions or undefined; }) => string` |
Parameters:
- `params.entries`: The entries of the documentation (functions, constants and classes).
- `params.options`: Optional configuration to render the Markdown content. See `types.ts` for details.
[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/lib/markdown.ts#L277)
### :gear: generateDocumentation
Generate documentation and write output to a file.
If the file exists, it will try to insert the docs between and comments.
If these does not exist, the output file will be overwritten.
| Function | Type |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `generateDocumentation` | `({ inputFiles, outputFile, markdownOptions, buildOptions }: { inputFiles: string[]; outputFile: string; markdownOptions?: MarkdownOptions or undefined; buildOptions?: BuildOptions or undefined; }) => void` |
Parameters:
- `params.inputFiles`: The list of files to scan for documentation. Absolute or relative path.
- `params.outputFile`: The file to output the documentation in Markdown.
- `params.markdownOptions`: Optional settings passed to the Markdown parser. See `MarkdownOptions` for details.
- `params.buildOptions`: Options to construct the documentation tree. See `BuildOptions` for details.
[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/lib/index.ts#L26)
## :books: Useful Resources
- [Using the TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
- [TypeScript AST Viewer](https://ts-ast-viewer.com/#)
- List of [TypeScript node kind](https://github.com/microsoft/TypeScript/blob/main/lib/typescript.d.ts)
## :sparkles: Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
David Dal Busco
💻 📖 💡 🤔 🚧 📆 🔬 👀 ⚠️ 🔧
Mia Riezebos
💻 📦 🔬 ⚠️
mingtianyihou
💻 ⚠️ 🤔
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## :page_facing_up: License
MIT © [David Dal Busco](mailto:[email protected])