Files

Juergen Kunz c084b20390 fix(package): Bump dependencies, refine test script and imports, and overhaul README and docs

2025-09-07 07:54:04 +00:00

8.1 KiB

Raw Blame History

@git.zone/tsdoc 🚀

AI-Powered Documentation for TypeScript Projects

Stop writing documentation. Let AI understand your code and do it for you.

What is tsdoc?

@git.zone/tsdoc is a next-generation documentation tool that combines traditional TypeDoc generation with cutting-edge AI to create comprehensive, intelligent documentation for your TypeScript projects. It reads your code, understands it, and writes documentation that actually makes sense.

✨ Key Features

🤖 AI-Enhanced Documentation - Leverages GPT-5 and other models to generate contextual READMEs
📚 TypeDoc Integration - Classic API documentation generation when you need it
💬 Smart Commit Messages - AI analyzes your changes and suggests meaningful commit messages
🎯 Context Optimization - Intelligent token management for efficient AI processing
📦 Zero Config - Works out of the box with sensible defaults
🔧 Highly Configurable - Customize every aspect when needed

Installation

# Global installation (recommended)
npm install -g @git.zone/tsdoc

# Or use with npx
npx @git.zone/tsdoc

Quick Start

Generate AI-Powered Documentation

# In your project root
tsdoc aidoc

That's it! tsdoc will analyze your entire codebase and generate:

A comprehensive README.md
Updated package.json description and keywords
Smart documentation based on your actual code

Generate Traditional TypeDoc

tsdoc typedoc --publicSubdir docs

Get Smart Commit Messages

tsdoc commit

CLI Commands

Command	Description
`tsdoc`	Auto-detects and runs appropriate documentation
`tsdoc aidoc`	Generate AI-enhanced documentation
`tsdoc typedoc`	Generate TypeDoc documentation
`tsdoc commit`	Generate smart commit message
`tsdoc tokens`	Analyze token usage for AI context
`tsdoc context`	Display context information

Token Analysis

Understanding token usage helps optimize AI costs:

# Show token count for current project
tsdoc tokens

# Show detailed stats for all task types
tsdoc tokens --all

# Test with trimmed context
tsdoc tokens --trim

Programmatic Usage

Generate Documentation Programmatically

import { AiDoc } from '@git.zone/tsdoc';

const generateDocs = async () => {
  const aiDoc = new AiDoc({ OPENAI_TOKEN: 'your-token' });
  await aiDoc.start();
  
  // Generate README
  await aiDoc.buildReadme('./');
  
  // Update package.json description
  await aiDoc.buildDescription('./');
  
  // Get smart commit message
  const commit = await aiDoc.buildNextCommitObject('./');
  console.log(commit.recommendedNextVersionMessage);
};

TypeDoc Generation

import { TypeDoc } from '@git.zone/tsdoc';

const typeDoc = new TypeDoc(process.cwd());
await typeDoc.compile({ publicSubdir: 'docs' });

Context Management

Control how tsdoc processes your codebase:

import { EnhancedContext } from '@git.zone/tsdoc';

const context = new EnhancedContext('./');
await context.initialize();

// Set token budget
context.setTokenBudget(100000);

// Choose context mode
context.setContextMode('trimmed'); // 'full' | 'trimmed' | 'summarized'

// Build optimized context
const result = await context.buildContext('readme');
console.log(`Tokens used: ${result.tokenCount}`);

Configuration

Configure tsdoc via npmextra.json:

{
  "tsdoc": {
    "context": {
      "maxTokens": 150000,
      "contextMode": "trimmed",
      "includePatterns": ["**/*.ts"],
      "excludePatterns": ["**/*.test.ts"],
      "trimming": {
        "removeImplementations": true,
        "preserveJSDoc": true,
        "removeComments": true
      }
    }
  }
}

How It Works

🔍 Code Analysis - Scans your TypeScript files, package.json, and existing documentation
✂️ Smart Trimming - Optimizes code context to fit within AI token limits
🧠 AI Processing - Sends optimized context to AI for analysis
📝 Generation - Creates documentation that understands your code's purpose and structure

Context Optimization

tsdoc employs sophisticated strategies to maximize the value of every token:

Intelligent Trimming - Removes implementation details while preserving signatures
Priority Sorting - Most important files first
Smart Summarization - Condenses large files while maintaining context
Token Budgeting - Ensures optimal use of AI context windows

Environment Variables

Variable	Description
`OPENAI_TOKEN`	Your OpenAI API key for AI features

Use Cases

🚀 Continuous Integration

# .github/workflows/docs.yml
- name: Generate Documentation
  run: |
    npm install -g @git.zone/tsdoc
    tsdoc aidoc

🔄 Pre-Commit Hooks

# Generate commit message before each commit
tsdoc commit

📦 Package Publishing

// Ensure docs are updated before publish
{
  "scripts": {
    "prepublishOnly": "tsdoc aidoc"
  }
}

Advanced Features

Multi-Module Projects

tsdoc automatically detects and documents multi-module projects:

const aiDoc = new AiDoc();
await aiDoc.start();

// Process main project
await aiDoc.buildReadme('./');

// Process submodules
for (const module of ['packages/core', 'packages/cli']) {
  await aiDoc.buildReadme(module);
}

Custom Context Building

Fine-tune what gets sent to AI:

import { TaskContextFactory } from '@git.zone/tsdoc';

const factory = new TaskContextFactory('./');
await factory.initialize();

// Get optimized context for specific tasks
const readmeContext = await factory.getContext('readme');
const commitContext = await factory.getContext('commit');

Performance

⚡ Fast - Parallel file processing and smart caching
💾 Efficient - Minimal memory footprint with streaming
🎯 Accurate - Context optimization ensures AI gets the most relevant code
💰 Cost-Effective - Token optimization reduces AI API costs

Requirements

Node.js >= 18.0.0
TypeScript project
OpenAI API key (for AI features)

Troubleshooting

Token Limit Exceeded

If you hit token limits, try:

# Use trimmed mode
tsdoc aidoc --trim

# Check token usage
tsdoc tokens --all

Missing API Key

Set your OpenAI key:

export OPENAI_TOKEN="your-key-here"
tsdoc aidoc

Why tsdoc?

🎯 Actually Understands Your Code - Not just parsing, but comprehension
⏱️ Saves Hours - Generate complete documentation in seconds
🔄 Always Up-to-Date - Regenerate documentation with every change
🎨 Beautiful Output - Clean, professional documentation every time
🛠️ Developer-Friendly - Built by developers, for developers

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

8.1 KiB Raw Blame History