https://github.com/charto/docts
README.md API section autogenerator for TypeScript projects
https://github.com/charto/docts
Last synced: 9 months ago
JSON representation
README.md API section autogenerator for TypeScript projects
- Host: GitHub
- URL: https://github.com/charto/docts
- Owner: charto
- License: mit
- Created: 2016-03-19T01:00:43.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2019-06-14T07:52:12.000Z (over 6 years ago)
- Last Synced: 2025-03-21T23:51:15.642Z (10 months ago)
- Language: TypeScript
- Size: 27.3 KB
- Stars: 22
- Watchers: 3
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
docts
=====
[](http://travis-ci.org/charto/docts)
[](https://david-dm.org/charto/docts)
[](https://www.npmjs.com/package/docts)
This is a command-line tool to generate API documentation for TypeScript projects
based on information about types and exported declarations extracted using [readts](https://github.com/charto/readts).
Run `docts` inside your package and it parses the `.d.ts` files referenced from the `typings` key of your `package.json`.
Then it replaces any section titled `API` in your `README.md` file with new automatically generated content.
For an example of its output, see the [API](#api) section below.
If your package is a Git working tree and the `repository` field in `package.json` points to a Github URL,
links to relevant parts of the code published on Github are added next to functions, classes and methods.
Each link looks like `<>` and includes the hash of the latest commit which changed the relevant file.
If that file is dirty in the working tree, the link points to whatever is on the current branch instead.
This minimizes changes to the links while trying to keep them pointed to the correct location in latest code.
Any additional TypeScript configuration should be defined in `tsconfig.json` in the root if your package.
Usage
-----
Start by making a backup of your `README.md`.
Then install:
```sh
npm install --save-dev docts
```
Make sure your `package.json` has a `typings` section and add in the `scripts` section:
```json
"scripts": {
"docts": "docts"
}
```
Finally run:
```sh
npm run docts
```
API
===
Docs generated using [`docts`](https://github.com/charto/docts)
>
>
> ### Class [`DocBuilder`](#api-DocBuilder)
> TypeScript project Markdown documentation builder.
> Source code: [`<>`](http://github.com/charto/docts/blob/db09800/src/DocBuilder.ts#L41-L284)
>
> Methods:
> > **new( )** ⇒ [DocBuilder](#api-DocBuilder) [`<>`](http://github.com/charto/docts/blob/db09800/src/DocBuilder.ts#L42-L59)
> > ▪ basePath string
> > **.build( )** ⇒ Promise<any> [`<>`](http://github.com/charto/docts/blob/db09800/src/DocBuilder.ts#L253-L270)
> > Generate API documentation for the package.
> > Returns promise resolving to an array of text split by line breaks.
>
>
> ### Class [`Markdown`](#api-Markdown)
> Represents a Markdown file.
> Source code: [`<>`](http://github.com/charto/docts/blob/1c6326e/src/Markdown.ts#L21-L82)
>
> Methods:
> > **new( )** ⇒ [Markdown](#api-Markdown) [`<>`](http://github.com/charto/docts/blob/1c6326e/src/Markdown.ts#L22-L24)
> > ▪ markdownPath string
> > **.readSections( )** ⇒ [Section](#api-Section)[] [`<>`](http://github.com/charto/docts/blob/1c6326e/src/Markdown.ts#L28-L67)
> > Read the file and split each heading into a separate section.
> > **.writeSections( )** ⇒ Promise<void> [`<>`](http://github.com/charto/docts/blob/1c6326e/src/Markdown.ts#L71-L79)
> > Replace file contents with a new list of sections.
> > ▪ sectionList [Section](#api-Section)[]
>
> Properties:
> > **.path** string
>
>
> ### Class [`Section`](#api-Section)
> Represents a section in a Markdown file.
> Source code: [`<>`](http://github.com/charto/docts/blob/1c6326e/src/Markdown.ts#L9-L17)
>
> Properties:
> > **.header** string[]
> > Heading and its markup split by newlines.
> > Heading is a line beginning with # or followed by another line full of - or =.
> > **.content** string[]
> > Section content split by newlines.
> > **.name** string
> > Heading with markup stripped.
>
>
> ### Function [`patchReadme`](#api-patchReadme)
> Patch section titled API of README.md file in given directory.
> Source code: [`<>`](http://github.com/charto/docts/blob/d74799b/src/Patcher.ts#L11-L27)
> > **patchReadme( )** ⇒ void [`<>`](http://github.com/charto/docts/blob/d74799b/src/Patcher.ts#L11-L27)
> > ▪ basePath string
License
=======
[The MIT License](https://raw.githubusercontent.com/charto/docts/master/LICENSE)
Copyright (c) 2016 BusFaster Ltd