Skip to content
/ docts Public

README.md API section autogenerator for TypeScript projects

License

Notifications You must be signed in to change notification settings

charto/docts

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

docts

build status dependency status npm version

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

TypeScript project Markdown documentation builder.
Source code: <>

Methods:

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

Class Markdown

Represents a Markdown file.
Source code: <>

Methods:

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

Properties:

.path string

Class Section

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

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

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

patchReadme( ) void <>
 ▪ basePath string

License

The MIT License

Copyright (c) 2016 BusFaster Ltd