https://github.com/kazupon/api-docs-gen
:book: API Documentation generator from `api-extractor` doc model
https://github.com/kazupon/api-docs-gen
api-extractor documentation generator tsdoc typescript
Last synced: 2 months ago
JSON representation
:book: API Documentation generator from `api-extractor` doc model
- Host: GitHub
- URL: https://github.com/kazupon/api-docs-gen
- Owner: kazupon
- License: mit
- Created: 2020-07-01T16:59:11.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-01-13T17:48:58.000Z (4 months ago)
- Last Synced: 2025-03-11T00:06:57.112Z (2 months ago)
- Topics: api-extractor, documentation, generator, tsdoc, typescript
- Language: TypeScript
- Homepage:
- Size: 1.35 MB
- Stars: 29
- Watchers: 3
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# đ api-docs-gen
[](https://www.npmjs.com/package/api-docs-gen)
API Documentation generator from `api-extractor` doc model
## đ¨ Requirement
You need to generate **doc model** with using [`api-extractor`](https://api-extractor.com/)
## đŋ Installation
### npm
```sh
$ npm install -g api-docs-gen
```
### yarn
```sh
yarn global api-docs-gen
```
### pnpm
```sh
pnpm add -g api-docs-gen
```
## đ Usage
### CLI
```
Usage
$ api-docs-gen ...
Options
--config, -c configration file
--output, -o output dierectory that is markdown contents
--generateStyle, -g document generating style, default 'prefix'
'prefix': be able to separated with each package name
'directory': be able to separated with each package directory
--tsdocConfig, -t tsdoc configration file
```
### đ¤ API
```javascript
const path = require('path')
const { genereate, DefaultConfig } = require('api-docs-gen')
// input
const input = [path.resolve(process.cwd(), './package1.api.json')]
// output
const output = path.resolve(process.cwd(), './docs')
// generate API docs with prefixed package name
await generate(input, output, { style: 'prefix', config: DefaultConfig })
```
About details, See the [API References](https://github.com/kazupon/api-docs-gen/blob/master/api-docs-gen-api.md)
## đ Examples
You can play API docs generation that have [multi packages](https://github.com/kazupon/api-docs-gen/tree/master/examples/packages).
You can play with the following command:
```sh
$ pnpm example:build # build on each package
$ pnpm example:extract # generate doc model with `api-extractor` on each package
$ pnpm example:gen # genearte API docs with `api-docs-gen`
$ pnpm example:docs # run vuepress
```
## đ TSDoc custom tags
`api-docs-gen` allows TSDoc custom tags to be processed using [tsdoc-config](https://github.com/microsoft/tsdoc/tree/master/tsdoc-config).
You can make it work from the `api-extractor` model by specifying tsdoc configration in the `--tsdoc-config` option as follows:
```bash
$ api-docs-gen package1.api.json --tsdoc-config ./tsdoc.json
```
If you want to output custom tags comment to markdown, you need to implement and configure the custom `MarkdownProcessor`.
For the `MarkdownProcessor`, see the [API References](https://github.com/kazupon/api-docs-gen/blob/master/api-docs-gen-api.md).
See how to configure it in the following configration.
## đ§ Configration
You can fully customize the generation of api docs using the config offered by `api-docs-gen`.
Here is the schema (typescript type definition) of the config:
```typescript
// There are two things you need to specify in config
export interface Config {
// A resolver that resolves references to links in markdown content
linkReferencer?: ReferenceResolver
// A processor that generates markdown content
processor: MarkdownProcessor
}
```
You can generate customized api docs by specifying these as you define them in your config, and the CLI `--config` option. `api-docs-gen` CLI will read `docsgen.config.js` as default.
api-docs-gen API docs is a TOC included markdown document. To generate the API docs, it use a customized resolver and processor for TOC.
- Configration: https://github.com/kazupon/api-docs-gen/blob/master/docsgen.config.js
- TOC reolsver: https://github.com/kazupon/api-docs-gen/blob/master/src/resolver/toc.ts
- TOC processor: https://github.com/kazupon/api-docs-gen/blob/master/src/processor/toc.ts
If you want to customize your api docs, these will be helpful.
It's recommended to refer to the [API References](https://github.com/kazupon/api-docs-gen/blob/master/api-docs-gen-api.md) for customization.
## đ Changelog
Details changes for each release are documented in the [CHANGELOG.md](https://github.com/kazupon/api-docs-gen/blob/master/CHANGELOG.md).
## â Issues
Please make sure to read the [Issue Reporting Checklist](https://github.com/kazupon/api-docs-gen/blob/master/.github/CONTRIBUTING.md#issue-reporting-guidelines) before opening an issue. Issues not conforming to the guidelines may be closed immediately.
## â
TODO
Managed with [GitHub Projects](https://github.com/kazupon/api-docs-gen/projects/2)
## Šī¸ License
[MIT](http://opensource.org/licenses/MIT)