readme-tsdoc

A simple tool that extracts documentation from TypeScript and JavaScript files and inserts it into your README.md. Using the TypeScript compiler API, readme-tsdoc generates documentation from JSDoc comments, type information, function signatures, parameters, return types, and examples to keep your API documentation in sync with your code.

Installation

npm install --save-dev readme-tsdoc

Usage

1. Add a marker comment (The following is auto-generated from) in your README.md where you want the documentation to appear. For example:

## API Documentation

You can introduce the API any way you like. This is left unchanged.
Now, here comes the magic phrase...

The following is auto-generated from `test/demo.ts`:

There can be multiple markers, for different files.

2. Run the tool:

npx readme-tsdoc

The tool will scan for marker phrases (like "The following is auto-generated from FILENAME") and replace everything between the marker and the next heading with generated documentation. It automatically adjusts heading levels based on the surrounding content.

Command Line Options

npx readme-tsdoc [options]

Options:

• --file <filename>: Specify README file to update (default: README.md)
• --search <phrase>: Custom search phrase (default: "The following is auto-generated from")
• --repo-url <url>: Optional repository (GitHub or GitLab) URL for generating deep links to source code (e.g., https://github.com/username/repo)

Examples:

# Update custom file
npx readme-tsdoc --file docs/api.md

# Use custom search phrase
npx readme-tsdoc --search "Auto-generated docs from" --repo-url "https://github.com/jdoe/my-repo"

Programmatic Usage

You can also use readme-tsdoc from your own code. The following docs are generated by the tool itself, though as the tool is written in JavaScript instead of TypeScript, the documentation is not as rich as it could be.

The following is auto-generated from src/readme-tsdoc.js:

generateMarkdownDoc · function

Generate markdown documentation for a TypeScript file using TypeScript compiler API

Signature: (filePath: string, headingPrefix: string, repoUrl?: string) => Promise<string>

Parameters:

• filePath: any - Path to the TypeScript file
• headingPrefix: any - The heading prefix to use (e.g., '###' for level 3)
• repoUrl: any - Optional repository URL for generating deep links (e.g., 'https://github.com/vanviegen/readme-tsdoc')

Returns: Generated markdown documentation

updateReadme · function

Update README file with auto-generated TypeScript documentation

Signature: (readmePath: string, searchPhrase: string, repoUrl?: string) => Promise<void>

Parameters:

• readmePath: any - Path to the README file to update
• searchPhrase: any - The phrase to search for in the README to mark sections for auto-generation
• repoUrl: any - Optional repository URL for generating deep links (e.g., 'https://github.com/vanviegen/readme-tsdoc')

Integrating with your build process

Add to your package.json:

{
  "scripts": {
    "docs": "readme-tsdoc",
    "prepublishOnly": "npm run docs"
  }
}

This ensures your documentation is always up-to-date before publishing.

Demo Output

The following is auto-generated from test/demo.ts:

celsiusToFahrenheit · function

Convert temperature between Celsius and Fahrenheit

Signature: (celsius: number) => number

Parameters:

• celsius: number - Temperature in Celsius

Returns: Temperature in Fahrenheit

Examples:

const fahrenheit = celsiusToFahrenheit(25);
console.log(fahrenheit); // 77

findMax · function

Generic function to find the maximum value in an array

Signature: <T>(items: T[], compareFn: (a: T, b: T) => number) => T

Type Parameters:

• T - The type of elements in the array

Parameters:

• items: T[] - Array of items to search
• compareFn: (a: T, b: T) => number - Comparison function to determine order

Returns: The maximum item, or undefined if array is empty

Examples:

const numbers = [1, 5, 3, 9, 2];
const max = findMax(numbers, (a, b) => a - b);
console.log(max); // 9

MathUtils · class

A utility class for mathematical operations and calculations

Constructor Parameters:

• precision: Number of decimal places for rounding (default: 2)

MathUtils.PI · static property

The mathematical constant PI

Type: number

Examples:

console.log(MathUtils.PI); // 3.141592653589793

MathUtils.circleArea · static method

Calculate the area of a circle

Signature: (radius: number) => number

Parameters:

• radius: number - The radius of the circle

Returns: The area of the circle

Throws:

• Error when radius is negative

Examples:

const area = MathUtils.circleArea(5);
console.log(area); // 78.53981633974483

mathUtils.precision · property

Current calculation precision for rounding operations

Type: number

mathUtils.round · method

Round a number to the specified precision

Signature: (value: number) => number

Parameters:

• value: number - The number to round

Returns: The rounded number

Examples:

const math = new MathUtils(3);
const rounded = math.round(3.14159);
console.log(rounded); // 3.142

mathUtils.currentPrecision · getter

Get the current precision setting

Type: number

mathUtils.currentPrecision · setter

Set a new precision value

Type: number

SPEED_OF_LIGHT · constant

A constant representing the speed of light in vacuum (m/s)

Value: 299792458

CONFIG · constant

Configuration object for mathematical operations

Value: { readonly defaultPrecision: 2; readonly strictMode: true; readonly maxIterations: 1000; }

About this project

• Created by Claude Sonnet & Frank van Viegen.
• ISC License - see LICENSE file for details.
• Contributions are welcome! Please feel free to submit a Pull Request.