CodeNarrator

🇷🇺 Русский гайд

CLI utility for automatic documentation generation from source code and GitHub Issues using AI.

CodeNarrator transforms your codebase and issue history into clear, up-to-date, and multilingual documentation. It uses AI to analyze code structure, extract meaningful descriptions, and generate comprehensive documentation.

Features

• Code Analysis: Parse Python and JavaScript/TypeScript code using Tree-sitter
• README Generation: Automatically generate comprehensive README files
• API Documentation: Create detailed API docs with function signatures and descriptions
• Architecture Diagrams: Generate Mermaid diagrams showing module dependencies
• FAQ Generation: Cluster GitHub Issues and generate FAQ entries
• Multilingual Support: Translate documentation to multiple languages (RU, ZH, ES, etc.)
• Multiple AI Providers: Support for OpenAI, Anthropic Claude, Ollama, and Z.AI (GLM models)
• Incremental Updates: Only regenerate changed files to save tokens

Installation

pip install codenarrator

Or using Poetry:

poetry add codenarrator

Quick Start

1. Initialize documentation

cd your-project
codenarrator init

This will:

• Scan your project structure
• Analyze entry points and dependencies
• Generate README.md, API docs, and architecture diagrams

2. Update documentation

codenarrator update

Only updates documentation for files that have changed.

3. Generate FAQ from GitHub Issues

codenarrator faq-sync --repo owner/repo

Fetches closed issues, clusters similar problems, and generates FAQ entries.

Configuration

Create a .narrator.yaml file in your project root:

version: 1

project:
  name: null # Auto-detected
  entry_points:
    - main.py
    - src/**/__init__.py

provider:
  type: openai # openai | anthropic | ollama
  model: gpt-4o

analysis:
  languages:
    - python
    - javascript
  ignore:
    - node_modules/**
    - .venv/**

faq:
  github_repo: owner/repo
  labels:
    - bug
    - question
  days_back: 30

localization:
  enabled: true
  languages:
    - ru
    - zh
    - es

output:
  docs_dir: docs

CLI Commands

codenarrator init

Initialize documentation for a project.

codenarrator init [PATH] [OPTIONS]

Options:
  -p, --provider TEXT  AI provider (openai, anthropic, ollama)
  -m, --model TEXT     Model to use for analysis
  -o, --output PATH    Output directory for documentation
  -l, --languages TEXT Target languages for localization

codenarrator update

Update documentation incrementally.

codenarrator update [PATH] [OPTIONS]

Options:
  --incremental  Update only changed files (default)
  --full         Regenerate all documentation

codenarrator faq-sync

Sync FAQ from GitHub Issues.

codenarrator faq-sync [PATH] [OPTIONS]

Options:
  -r, --repo TEXT    GitHub repository (owner/repo)
  -d, --days INTEGER Days to look back
  --labels TEXT      Issue labels to filter

codenarrator config

Manage configuration.

codenarrator config [PATH] [OPTIONS]

Options:
  -s, --show  Show current configuration

Environment Variables

• OPENAI_API_KEY: OpenAI API key
• ZAI_API_KEY: Z.AI API key (alternative to OPENAI_API_KEY)
• ANTHROPIC_API_KEY: Anthropic API key
• GITHUB_TOKEN: GitHub personal access token (for FAQ generation)
• OLLAMA_BASE_URL: Ollama API URL (default: http://localhost:11434)

AI Providers

OpenAI

codenarrator init --provider openai --model gpt-4o

Anthropic Claude

codenarrator init --provider anthropic --model claude-3-opus-20240229

Ollama (Local)

codenarrator init --provider ollama --model llama2

Z.AI GLM Models

codenarrator init --provider openai --model GLM-4.7

# Or use config file (.narrator.yaml):
provider:
  type: openai
  model: GLM-4.7
  base_url: https://api.z.ai/api/coding/paas/v4

See .narrator.zai.example.yaml for full Z.AI configuration example or ZAI_SETUP.md for detailed setup guide.

Supported Languages

Code Analysis

• Python
• JavaScript
• TypeScript

Documentation Translation

• English (base)
• Russian (ru)
• Chinese Simplified (zh)
• Spanish (es)
• French (fr)
• German (de)
• Japanese (ja)
• Korean (ko)
• Portuguese (pt)
• Italian (it)

Project Structure

your-project/
├── .narrator.yaml       # Configuration
├── .narrator/
│   └── cache.json       # Cache for incremental updates
├── docs/
│   ├── README.md        # Main documentation
│   ├── api/             # API documentation
│   ├── architecture.md  # Architecture diagrams
│   └── FAQ.md          # Generated FAQ
└── README.ru.md         # Localized versions

Development

Setup

git clone https://github.com/codenarrator/codenarrator
cd codenarrator
poetry install

Testing

poetry run pytest

Type Checking

poetry run mypy src/codenarrator

Linting

poetry run ruff check src/

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

Acknowledgments

• Tree-sitter for fast AST parsing
• OpenAI and Anthropic for AI capabilities
• Typer for the CLI framework
• Rich for beautiful terminal output