Awesome

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. 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 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:

npm install --save-dev docts

Make sure your package.json has a typings section and add in the scripts section:

  "scripts": {
    "docts": "docts"
  }

Finally run:

npm run docts

API

Docs generated using docts

<a name="api-DocBuilder"></a>

Class DocBuilder

<em>TypeScript project Markdown documentation builder.</em>
Source code: <>

Methods:

new( ) ^{⇒ <code>DocBuilder</code>} <>
 ▪ basePath ^{<code>string</code>}
.build( ) ^{⇒ <code>Promise<any></code>} <>
 <em>Generate API documentation for the package.</em>
 <em>Returns promise resolving to an array of text split by line breaks.</em>

<a name="api-Markdown"></a>

Class Markdown

<em>Represents a Markdown file.</em>
Source code: <>

Methods:

new( ) ^{⇒ <code>Markdown</code>} <>
 ▪ markdownPath ^{<code>string</code>}
.readSections( ) ^{⇒ <code>Section[]</code>} <>
 <em>Read the file and split each heading into a separate section.</em>
.writeSections( ) ^{⇒ <code>Promise<void></code>} <>
 <em>Replace file contents with a new list of sections.</em>
 ▪ sectionList ^{<code>Section[]</code>}

Properties:

.path ^{<code>string</code>}

<a name="api-Section"></a>

Class Section

<em>Represents a section in a Markdown file.</em>
Source code: <>

Properties:

.header ^{<code>string[]</code>}
 <em>Heading and its markup split by newlines.</em>
 <em>Heading is a line beginning with # or followed by another line full of - or =.</em>
.content ^{<code>string[]</code>}
 <em>Section content split by newlines.</em>
.name ^{<code>string</code>}
 <em>Heading with markup stripped.</em>

<a name="api-patchReadme"></a>

Function patchReadme

<em>Patch section titled API of README.md file in given directory.</em>
Source code: <>

patchReadme( ) ^{⇒ <code>void</code>} <>
 ▪ basePath ^{<code>string</code>}

License

The MIT License

Copyright (c) 2016 BusFaster Ltd