tsdoc-markdown
v0.6.3
Published
Generates markdown documentation from TypeScript source code.
Downloads
9,327
Maintainers
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.
:1234: Table of contents
- :1234: Table of contents
- :arrow_down: Installation
- :electric_plug: GitHub Actions
- :zap: Usage
- :toolbox: Functions
- :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
.
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
: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
: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. Seetypes.ts
for details.
: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. SeeMarkdownOptions
for details.params.buildOptions
: Options to construct the documentation tree. SeeBuildOptions
for details.
:books: Useful Resources
: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