Readme LLM Generator

Intelligent Documentation Generator powered by AI

Readme LLM Generator is a powerful command-line tool that revolutionizes documentation creation by automatically analyzing your entire codebase and generating comprehensive, high-quality documentation using advanced AI language models. It offers two distinct modes: comprehensive project documentation that creates single README-style overviews perfect for onboarding and stakeholder communication, and enhanced per-file documentation with quality validation for detailed API references and code analysis. The tool intelligently understands code context, relationships between components, and architectural patterns to produce human-readable documentation that explains both technical implementation and business logic. With flexible file pattern configuration, quality scoring, and support for any programming language, it transforms the time-consuming task of documentation maintenance into an automated, consistent process.

🎯 Problem It Solves

Documentation is critical but time-consuming. Most developers struggle with:

• Manual Documentation Overhead: Writing and maintaining documentation takes significant time away from coding
• Inconsistent Quality: Documentation quality varies greatly between team members and projects
• Outdated Information: Documentation quickly becomes stale as code evolves
• Knowledge Silos: Complex codebases become difficult for new team members to understand
• Missing Context: Code comments alone don't capture architectural decisions and business logic

Readme LLM Generator solves these problems by:

✅ Automated Analysis: Intelligently scans your entire codebase to understand structure and relationships
✅ AI-Powered Generation: Uses advanced language models to create human-readable documentation that captures both technical details and business context
✅ Multiple Documentation Modes: Choose between comprehensive project overviews or detailed per-file documentation
✅ Quality Validation: Built-in validation ensures generated documentation meets quality standards
✅ Flexible Configuration: Customizable patterns to include/exclude files and directories
✅ Multi-Language Support: Works with any programming language or file type

🚀 Key Features

📊 Comprehensive Project Analysis

• Analyzes project structure, dependencies, and architecture patterns
• Identifies key components and their relationships
• Generates single comprehensive README-style documentation

🔍 Enhanced Per-File Documentation

• Creates detailed documentation for individual files
• Includes validation and quality scoring
• Provides improvement suggestions and detailed reporting

⚡ Smart File Indexing

• Flexible include/exclude patterns using glob syntax
• Intelligent defaults that skip build artifacts and temporary files
• Configurable via YAML configuration files

🤖 AI-Powered Intelligence

• Leverages advanced language models (currently using Google Gemini provider)
• Understands code context, not just syntax
• Generates documentation that explains "why" not just "what"

📈 Quality Assurance

• Built-in validation scoring system
• Retry mechanisms for failed generations
• Detailed quality reports with improvement recommendations

🛠️ Installation

Manual Installation

git clone https://github.com/sv222/readme-llm-generator.git
cd readme-llm-generator
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# Linux/MacOS
./.venv/bin/activate

pip install -r requirements.txt

Interactive TUI Setup

git clone https://github.com/sv222/readme-llm-generator.git
cd readme-llm-generator
python setup.py

⚙️ Configuration

1. Get AI Provider API Key

Current Provider: Google Gemini

1. Visit Google AI Studio
2. Create a new API key
3. Copy the key for configuration

2. Environment Setup

Create a .env file in the project root:

GEMINI_API_KEY=your_actual_api_key_here
GEMINI_MODEL=gemini-2.5-flash

3. Exclusion Patterns (Optional)

Create a config.yaml file to customize which files to process:

exclude:
  directories:
    - .venv
    - node_modules
    - build
    - dist
    - __pycache__
    - .git
    - .pytest_cache
    - .idea
    - .vscode
  files:
    - .*
    - "*.bin"
    - "*.exe"
    - "*.log"
    - "*.pyc"
    - "*.tmp"
    - "*.min.*"

📖 Usage

Basic Commands

# Show help and all available options
python -m src index --help

# Analyze current directory (comprehensive mode - default)
python -m src index

# Analyze specific directory
python -m src index /path/to/your/project

Documentation Modes

Readme LLM Generator offers two distinct documentation approaches, each optimized for different use cases:

🏗️ Comprehensive Project Documentation (Default)

Best for: Project overviews, onboarding, and high-level understanding

Generate a single comprehensive README-style document that provides a complete project overview:

# Default comprehensive mode
python -m src index

# Explicitly specify comprehensive mode
python -m src index --comprehensive

# Custom output directory
python -m src index --output-dir ./documentation

What you get:

• Single unified document (like a GitHub README)
• Project architecture overview with system design explanations
• Complete project structure with directory and file explanations
• Core components analysis and their relationships
• Dependencies and integrations documentation
• Getting started guide with setup and usage examples
• API reference for public interfaces
• Development workflow and testing information

Perfect for:

• New team member onboarding
• Project documentation for stakeholders
• High-level system understanding
• README file generation
• Documentation for open source projects

🔍 Enhanced Per-File Documentation

Best for: Detailed code analysis, API documentation, and thorough code review

Generate detailed documentation for each individual file with quality validation and reporting:

# Enhanced mode with validation and reporting
python -m src index --enhanced

# Enhanced mode with custom output
python -m src index --enhanced --output-dir ./detailed-docs

What you get:

• Individual file documentation for each source file
• Quality scoring system (0.0-1.0) for each generated document
• Validation and retry mechanisms for failed generations
• Detailed quality report with improvement recommendations
• Function and class documentation with parameter details
• Code examples and usage patterns for each component
• Cross-references between related files and functions
• Performance metrics and generation statistics

Perfect for:

• Detailed API documentation
• Code review preparation
• Legacy code analysis
• Comprehensive code documentation
• Quality-focused documentation projects

📊 Mode Comparison

Feature	Comprehensive Mode	Enhanced Mode
Output	Single document	Multiple files
Focus	Project overview	Individual files
Detail Level	High-level architecture	Deep code analysis
Quality Control	Basic	Advanced with scoring
Generation Time	Fast	Slower (more thorough)
Best For	README, onboarding	API docs, code review
File Count	1 main document	1 per source file + report
Validation	None	Quality scoring & retry
Reporting	Basic stats	Detailed quality report

File Pattern Control

# Include specific file patterns (can use multiple times)
python -m src index --include="*.py" --include="*.js" --include="*.md"

# Exclude specific patterns (can use multiple times)
python -m src index --exclude="*.test.js" --exclude="temp/*" --exclude="*.min.*"

# Combine include and exclude patterns
python -m src index --include="src/**/*.py" --exclude="src/tests/*"

AI Model Configuration

# Use recommended model (2.5 generation)
python -m src index --model="gemini-2.5-flash"

# Use advanced model for complex projects
python -m src index --model="gemini-2.5-pro"

# Provide API key directly (overrides .env file)
python -m src index --api-key="your-api-key-here"

# Combine API key with recommended model
python -m src index --api-key="your-key" --model="gemini-2.5-flash"

Complete Flag Reference

Flag	Short	Description	Example
--include	-i	Include file patterns (glob syntax)	--include="*.py"
--exclude	-e	Exclude file patterns (glob syntax)	--exclude="*.test.*"
--output-dir	-o	Output directory for documentation	--output-dir="./docs"
--api-key	-k	AI provider API key	--api-key="your-key"
--model	-m	AI model name	--model="gemini-2.5-flash"
--comprehensive		Generate single project overview (default)	--comprehensive
--enhanced		Use enhanced per-file processor with validation	--enhanced

| --help | | Show help message and exit | --help |

Advanced Usage Examples

# Full-featured comprehensive documentation
python -m src index \
  --comprehensive \
  --include="*.py" --include="*.js" --include="*.md" \
  --exclude="*test*" --exclude="*.min.*" \
  --output-dir="./project-docs" \
  --model="gemini-2.5-pro"

# Enhanced mode with quality validation
python -m src index \
  --enhanced \
  --include="src/**/*.py" \
  --exclude="src/tests/*" \
  --output-dir="./api-docs"



# Process specific project directory
python -m src index ./my-project \
  --comprehensive \
  --output-dir="./my-project-docs"

📋 Available AI Models

Current Provider: Google Gemini

🌟 Recommended Models (Latest Generation)

• gemini-2.5-flash - ⭐ RECOMMENDED - Fast and efficient, perfect for most projects
• gemini-2.5-pro - ⭐ RECOMMENDED - Most advanced model for complex analysis and large codebases
• gemini-2.5-flash-lite - Efficient model for quick processing

Current Generation

• gemini-1.5-flash - Fast and efficient (default for compatibility)
• gemini-1.5-pro - More capable analysis for complex codebases
• gemini-2.0-flash - Fast model with improved capabilities
• gemini-2.0-flash-lite - Lightweight version

Legacy Models

• gemini-1.0-pro - Legacy model (not recommended for new projects)

💡 Tip: For best results, use gemini-2.5-flash for general documentation or gemini-2.5-pro for complex projects requiring detailed analysis.

📁 Output Structure

Comprehensive Mode

docs/
└── your-project/
    └── your-project_README.md  # Single comprehensive document

Enhanced Mode

docs/
└── your-project/
    ├── src/
    │   ├── main.py.md
    │   └── utils.py.md
    ├── tests/
    │   └── test_main.py.md
    └── DOCUMENTATION_REPORT.md  # Quality report

🎯 Use Cases

For Development Teams

• Onboarding: Help new team members understand codebase architecture
• Code Reviews: Generate documentation to accompany pull requests
• Knowledge Transfer: Capture institutional knowledge before team changes

For Open Source Projects

• Contributor Guides: Make it easier for contributors to understand project structure
• API Documentation: Auto-generate comprehensive API references
• Architecture Docs: Explain design decisions and patterns

For Legacy Codebases

• Reverse Engineering: Understand undocumented legacy systems
• Modernization: Document existing systems before refactoring
• Compliance: Generate documentation for audit and compliance requirements

🔧 Advanced Configuration

Custom Exclusion Patterns

The config.yaml file supports flexible exclusion patterns:

exclude:
  directories:
    - .venv
    - .env
    - build
    - dist
    - __pycache__
    - node_modules
    - .git
    - .pytest_cache
    - .mypy_cache
    - target
    - .idea
    - .vscode
    - "*.egg-info"
  files:
    - .*
    - "*.bin"
    - "*.exe"
    - "*.pyc"
    - "*.pyo" 
    - "*.pyd"
    - "*.log"
    - "*.tmp"
    - "*.cache"
    - "*.min.js"
    - "*.min.css"
    - "*.map"
    - ".DS_Store"
    - "Thumbs.db"

Environment Variables

All configuration can be set via environment variables:

# Required: AI provider API key (currently Google Gemini)
GEMINI_API_KEY=your_key_here

# Optional: AI model (recommended: gemini-2.5-flash)
GEMINI_MODEL=gemini-2.5-flash

# Optional: Default output directory
README_LLM_GENERATOR_OUTPUT_DIR=./docs

# Optional: Default include patterns (comma-separated)
README_LLM_GENERATOR_INCLUDE_PATTERNS=*.py,*.js,*.md,*.ts

# Optional: Default exclude patterns (comma-separated)
README_LLM_GENERATOR_EXCLUDE_PATTERNS=*.test.*,*.spec.*,temp/*,*.min.*

🔧 Troubleshooting

Common Issues

API Key Issues

# Test your API key
python -c "import os; print('API Key found' if os.getenv('GEMINI_API_KEY') else 'API Key missing')"

# Set API key temporarily (current provider: Google Gemini)
set GEMINI_API_KEY=your-key-here  # Windows CMD
$env:GEMINI_API_KEY="your-key-here"  # Windows PowerShell

Module Not Found Errors

# Ensure virtual environment is activated
.\.venv\Scripts\Activate.ps1

# Reinstall dependencies
pip install -r requirements.txt

# Test installation
python -m src --help

Permission Errors

# Run as administrator if needed (Windows)
# Or check file permissions for output directory

Memory Issues with Large Projects

# Use include patterns to process smaller subsets
python -m src index --include="src/**/*.py" --exclude="tests/*"

# Use comprehensive mode for lighter processing
python -m src index --comprehensive

Getting Help

1. Check the help: python -m src index --help
2. Verify setup: Run the TUI setup again with python setup.py
3. Test with small project: Try on a single file first
4. Check logs: Look for error messages in the console output

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: pytest tests/
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Setup

git clone https://github.com/yourusername/readme-llm-generator.git
cd readme-llm-generator
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Running Tests

# Activate virtual environment first
.\.venv\Scripts\Activate.ps1

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

Contributing

We welcome contributions from the community. If you have ideas, bug reports, or feature requests, please open an issue or submit a pull request.

License

This project is licensed under the MIT License.# readme-llm-generator