tsdoc-markdown

Generates markdown documentation from TypeScript source code. Useful for generating docs from code and injecting automatically the outcome into project README files.

:1234: Table of contents

• :1234: Table of contents
• :arrow_down: Installation
• :electric_plug: GitHub Actions
• :zap: Usage
• :toolbox: Functions
  • :gear: buildDocumentation
  • :gear: documentationToMarkdown
  • :gear: generateDocumentation
• :books: Useful Resources
• :sparkles: Contributors
• :page_facing_up: License

:arrow_down: Installation

Install the library in your project from npm:

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.

:zap: Usage

This tool is shipped with a NodeJS bin script tsdoc that can be added to your package.json.

e.g. generating the documentation for a source file ./src/index.ts:

{
  "script": {
    "tsdoc": "tsdoc --src=src/index.ts"
  }
}

The --src parameter accepts a comma separated list of paths and wildcards as well.

e.g.

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 also opt-out of generating titles with emojis by using the option --noemoji.

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.

#!/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
• documentationToMarkdown
• 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

: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

: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

:books: Useful Resources

• Using the TypeScript Compiler API
• TypeScript AST Viewer
• List of TypeScript node kind

:sparkles: Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

:page_facing_up: License

MIT © David Dal Busco