docgen

docgen

docgen is an efficient and sophisticated project documentation generator designed to compile an entire project's structure and source code into a single, accessible text file. This tool is particularly beneficial for sharing comprehensive project context with Language Learning Models (LLMs) — simply upload one file in an AI chat to facilitate discussions about the entire project.

Key Features

• 🌳 Visual Directory Structure: Generates a visual representation of the project layout.
• 📄 Combined File Content: Consolidates file contents into one document, complete with clear separators for easy navigation.
• 🎯 Intelligent Filtering: Respects .gitignore rules and allows for custom exclusions to maintain relevant content.
• 🚫 Automatic Binary Detection: Excludes binary files such as images, executables, and PDFs to ensure clean documentation.
• ⚙️ Configurable Options: Customize the documentation process with a .docgen_ignore file.
• 🔄 Git Integration: Utilizes git check-ignore to implement accurate filtering based on repository settings.
• 📊 File Size Management: Automatically skips files larger than 2MB by default to streamline the output.

Usage Instructions

Run docgen from the root directory of your project to generate documentation:

# Generate documentation, creating project_doc.txt
docgen
# Preview files for inclusion
docgen --files-list
# Display directory tree structure
# With symbols
 docgen --graphic-tree
# Plain text version
 docgen --plain-tree
# Specify a custom output location
 docgen --output docs/my_project.txt

Configuration Options

A .docgen_ignore file can be added to your project root to precisely control which files are included or excluded. The file follows .gitignore syntax:

# Always include
!.gitignore
!some_important_non_binary_file.foo
# Exclude patterns
.git/
log/
scratch.txt
junk/

If no .docgen_ignore file is present, docgen applies default rules for inclusion and exclusion, ensuring a streamlined experience.

How It Works

1. Directory Traversal: Scans all project files recursively.
2. File Type Filtering: Skips binary file types quickly.
3. Content Analysis: Reviews file content to identify binaries and previous docgen outputs.
4. Git Compatibility: Applies git configuration for up-to-date file management.
5. Custom Exclusions: Integrates additional custom rules for filtering.
6. Output Generation: Produces a comprehensive file detailing the project structure and file contents.

Example Output Format

The generated project_doc.txt will contain a clear structure:

# DOCGEN-OUTPUT: This file is generated by docgen. Do not include in next generation.

>>>> PROJECT FILE TREE: >>>>>>>>>>>>>>>>>>>>>>>>>>
.
├── main.go
├── README.md
└── go.mod

<<<< END OF FILE TREE: <<<<<<<<<<<<<<<<<<<<<<<<<<<

>>>> FILE CONTENTS: main.go >>>>>>>>>>>>>>>>>>>>>>>
package main
...

<<<< END OF FILE: main.go <<<<<<<<<<<<<<<<<<<<<<<<

Use Cases

• 📤 Integration with LLMs: Provide AI assistants with complete project context.
• 👀 Code Review Support: Easy-to-understand snapshots of the project.
• 📚 Documentation Generation: Automatically create an overview of your project.
• 🔍 Audit Preparation: Conduct thorough scans of the entire codebase.
• 📊 Tracking Changes: Monitor project evolution through diffs in generated outputs.

Benefits of Committing project_doc.txt

Committing the generated documentation to your version control system is advisable due to:

• Increased Visibility: Observe how project documentation evolves through time.
• Enhanced Accessibility: New contributors can quickly get up to speed by accessing the documentation.
• Better Tracking: Documentation changes can be aligned with code changes, enriching the project's overall history.

Contributors are welcomed. For suggestions, issues, or pull requests, feel free to engage with the project.