📄 Codebase-Doc

A streamlined Python tool that generates comprehensive markdown documentation of your codebase. It creates a tree view of your directory structure and includes the contents of all files with proper syntax highlighting.

Note

Originally inspired by CodeWeaver, reimplemented in Python with additional features like clipboard and .gitignore support.

✨ Features

• 🌳 Tree View: Clear, hierarchical visualization of your project structure
• 🎨 Syntax Highlighting: Automatic language detection based on file extensions
• 📋 Clipboard Support: Direct copy to clipboard for easy sharing
• 🚫 Smart Filtering:
  • Configurable regex patterns for ignoring files/directories
  • Native .gitignore support
  • Optional tracking of included/excluded paths
• 🛡️ Robust Handling:
  • UTF-8 encoding with fallback error handling
  • Permission error handling
  • Rich console output with color-coded status indicators

🚀 Quick Start

# Install with pipx (recommended)
pipx install -e .

# Generate documentation for current directory
codebase-doc

# Or specify a custom directory and output file
codebase-doc -i /path/to/project -o docs.md

# Copy to clipboard instead of file
codebase-doc -c

🛠️ Installation

Requires Python 3.7 or higher.

Using pipx (Recommended)

pipx install -e .

This installs the package in an isolated environment while allowing you to make changes to the source code.

📖 Usage

Command Line Options

codebase-doc [-h] [-i INPUT] [-o OUTPUT] [-c] [--ignore IGNORE]
             [--included-paths INCLUDED_PATHS] [--excluded-paths EXCLUDED_PATHS]
             [--skip-gitignore] [-v]

Option	Description	Default
-i, --input	Directory to scan	Current directory
-o, --output	Output file name	documentation.md
-c, --clipboard	Copy to clipboard instead of file	False
--ignore	Comma-separated regex patterns to ignore	\.git.*|__pycache__
--included-paths	Save list of included paths to file	None
--excluded-paths	Save list of excluded paths to file	None
--skip-gitignore	Skip loading .gitignore files	False
-v, --version	Show version and exit
-h, --help	Show help message

Example Commands

# Basic usage with default settings
codebase-doc

# Scan a specific directory
codebase-doc -i /path/to/project

# Copy output to clipboard
codebase-doc -c

# Custom ignore patterns
codebase-doc --ignore "\.git.*,\.venv,node_modules"

# Track included and excluded paths
codebase-doc --included-paths included.txt --excluded-paths excluded.txt

# Skip .gitignore rules
codebase-doc --skip-gitignore

📋 Output Format

The generated markdown file contains two main sections:

1. Tree View: A hierarchical representation of your codebase structure

   ├─src
   │ ├─main.py
   │ └─utils.py
   ├─tests
   │ └─test_main.py
   └─README.md
   

2. Content: The contents of each file with appropriate syntax highlighting

   ## src/main.py
   
   ```python
   def main():
       print("Hello, World!")
   ```

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.