🧙 Project Guide

Your magical AI-powered project documentation generator

Ever wished your project could explain itself? Now it can! 🪄 Project Guide uses AI to analyze your codebase and generate comprehensive documentation automagically.

✨ Features

🔍 Deep code analysis
📚 Generates detailed developer guides
🎯 Identifies project purpose and architecture
🗺️ Creates clear documentation structure
🤖 AI-powered insights
📝 Markdown-formatted output
🔄 Recursive directory analysis
🎨 Well-organized documentation

Checkout the guidebook.md and guidebook-components.md in my other repo to see an example of what is generated: https://github.com/sojohnnysaid/vim-restman

guidebook.md is a medium-high level overview
guidebook-components.md is an indepth look at individual modules/functions and their inputs/outputs, including how they fit into the bigger picture.

🚀 Quick Start

Prerequisites

Python 3.8+
Anthropic API key
Your favorite code project to document!

Installation

Clone this repository:

git clone https://github.com/yourusername/project-guide.git
cd project-guide

Create a virtual environment (recommended):

python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Set up your environment variables:

export ANTHROPIC_API_KEY="your-api-key-here"
export GUIDE_TARGET_PROJECT_DIRECTORY="/path/to/your/project"

Run the magic spell:

python guide.py

📦 Output

The script creates three magical artifacts:

📘 initial-summaries_{timestamp}.txt - Raw project insights
🗄️ findings/{timestamp}/findings.json - Structured analysis data
📚 guidebook_{timestamp}.md - Your beautiful developer guide!

🎯 Usage Tips

🧹 The script automatically excludes common non-source directories (.git, node_modules, etc.)
🔮 Works best with well-organized codebases
📏 Large projects may take longer to analyze
💡 The better organized your code, the better the documentation!

⚙️ Configuration

Want to exclude more directories? Modify the EXCLUSION_LIST in the script:

EXCLUSION_LIST = [
    '.git', 
    '.venv', 
    'node_modules', 
    '__pycache__', 
    '.DS_Store',
    'pb_data',
    'pb_public',
    'migrations'
]

🎨 Example Output Structure

📁 Your Project
├── 📄 initial-summaries_20240122_123456.txt
├── 📁 findings
│   └── 📁 20240122_123456
│       └── 📄 findings.json
└── 📄 guidebook_20240122_123456.md

🛟 Troubleshooting

Common Issues:

API Key Error

# Make sure your API key is set:
echo $ANTHROPIC_API_KEY  # Should show your key

Project Directory Error

# Verify your project directory is set and exists:
echo $GUIDE_TARGET_PROJECT_DIRECTORY
ls $GUIDE_TARGET_PROJECT_DIRECTORY

Virtual Environment Issues

# Make sure you're in the virtual environment:
# You should see (.venv) in your terminal
# If not, activate it:
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

🤝 Contributing

Got ideas to make Project Guide even more magical? Contributions are welcome!

🍴 Fork the repo
🌱 Create your feature branch
💫 Make your changes
🚀 Submit a PR

📜 License

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

✨ Acknowledgments

🤖 Powered by Anthropic's Claude API
🧙‍♂️ Inspired by all the developers who hate writing documentation
🌟 Special thanks to coffee and late-night coding sessions

Made with 💜 and a bit of AI magic

Remember: Documentation is like a love letter to your future self! 💌

sojohnnysaid/project-guide