Metadata-Version: 2.4
Name: codenarrator
Version: 0.1.0
Summary: CLI utility for automatic documentation generation from source code and GitHub Issues using AI
Author: CodeNarrator Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/xuviga/codenarrator
Project-URL: Repository, https://github.com/xuviga/codenarrator
Project-URL: Issues, https://github.com/xuviga/codenarrator/issues
Keywords: documentation,ai,code-analysis,openai,anthropic,ollama
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: openai>=1.12.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tree-sitter>=0.21.3
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: jinja2>=3.1.3
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Requires-Dist: black>=24.2.0; extra == "dev"
Dynamic: license-file

# CodeNarrator

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-generated-brightgreen.svg)](docs/)
[🇷🇺 Русский гайд](USAGE_GUIDE_RU.md)

**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

```bash
pip install codenarrator
```

Or using Poetry:

```bash
poetry add codenarrator
```

## Quick Start

### 1. Initialize documentation

```bash
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

```bash
codenarrator update
```

Only updates documentation for files that have changed.

### 3. Generate FAQ from GitHub Issues

```bash
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:

```yaml
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.

```bash
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.

```bash
codenarrator update [PATH] [OPTIONS]

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

### `codenarrator faq-sync`

Sync FAQ from GitHub Issues.

```bash
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.

```bash
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
```bash
codenarrator init --provider openai --model gpt-4o
```

### Anthropic Claude
```bash
codenarrator init --provider anthropic --model claude-3-opus-20240229
```

### Ollama (Local)
```bash
codenarrator init --provider ollama --model llama2
```

### Z.AI GLM Models
```bash
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](.narrator.zai.example.yaml) for full Z.AI configuration example or [ZAI_SETUP.md](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

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

### Testing

```bash
poetry run pytest
```

### Type Checking

```bash
poetry run mypy src/codenarrator
```

### Linting

```bash
poetry run ruff check src/
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

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

## Acknowledgments

- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) for fast AST parsing
- [OpenAI](https://openai.com/) and [Anthropic](https://www.anthropic.com/) for AI capabilities
- [Typer](https://typer.tiangolo.com/) for the CLI framework
- [Rich](https://github.com/Textualize/rich) for beautiful terminal output
