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

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.

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 <path>: README file to update (default: README.md). When used with --create, specifies the output file.
--search <phrase>: Custom search phrase (default: "The following is auto-generated from").
--create <source>: TypeScript source file; generate reference docs and write them to --file. Mutually exclusive with --search.
--repo-url <url>: Optional repository (GitHub or GitLab) URL for generating deep links to source code (e.g., https://github.com/username/repo).
--split: Make the primary output an overview document, with links to separate markdown files for each method/function/class/etc containing details.

There are two modes:

Update mode (default): reads --file, searches for marker phrases like "The following is auto-generated from \FILENAME`”`, and replaces the following section with generated documentation. Heading levels are adjusted to match the surrounding content.

Create mode (--create <source>): generates reference documentation directly from the given TypeScript source file and writes it to --file, overwriting any existing content. --file is required in this mode.

Examples:

# Update markers in README.md (default)
npx readme-tsdoc

# Update markers in a different file
npx readme-tsdoc --file docs/api.md --search "Auto-generated docs from" --repo-url "https://github.com/jdoe/my-repo"

# Create a standalone reference doc from a source file, split into per-symbol files
npx readme-tsdoc --file docs/api-reference.md --create src/index.ts --split

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, split?: boolean) => 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’)
split: any - When true, generate split documentation with brief overview in main file and details in separate files

createDocs · function

Generate reference documentation for a TypeScript source file and write it to an output file.

Signature: (sourcePath: string, outputPath: string, repoUrl?: string, split?: boolean) => void

Parameters:

sourcePath: any - Path to the TypeScript source file
outputPath: any - Path to the output file (will be overwritten)
repoUrl: any - Optional repository URL for generating deep links
split: any - When true, split documentation into multiple files

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.