# 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 [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#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`. You can opt-out of generating titles with emojis by using the option `--noemoji`. You can also opt-out of documenting entries marked with a `@internal` JSDoc tag by using the option `--skipInternal`. 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) - [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 Returns: An array of documentation entries [:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/lib/docs.ts#L604) ### :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
David Dal Busco
💻 📖 💡 🤔 🚧 📆 🔬 👀 ⚠️ 🔧		 Mia Riezebos
Mia Riezebos
💻 📦 🔬 ⚠️		 mingtianyihou
mingtianyihou
💻 ⚠️ 🤔		 Erik Jan de Wit
Erik Jan de Wit
💬 💻 🤔		 Andy Hall
Andy Hall
💻 ⚠️ 🤔
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:david.dalbusco@outlook.com)