- Overview
- Features
- Supported Languages
- Installation
- Configuration
- Usage
- How It Works
- Customization
- Contributing
- License
- Contact
The AI-Driven Code Documentation Generator automates the creation of structured documentation for codebases. Utilizing OpenAI's GPT-4 (or Azure OpenAI) and advanced parsing techniques, it extracts code structures and generates insightful docstrings. This tool enhances maintainability and collaboration for projects of any size.
-
Multi-Language Support: Automatically generates documentation for Python, JavaScript, TypeScript, Go, C++, Java, HTML, and CSS.
-
Structured Documentation: Produces JSON-based documentation conforming to a predefined schema for consistency and ease of use.
-
Google-Style Docstrings: Inserts detailed, Google-style docstrings into your codebase.
-
Asynchronous Processing: Efficiently handles large codebases with asynchronous file processing.
-
Customizable Prompts: Tailor AI prompts to fit your project's specific documentation needs.
-
Comprehensive Logging: Detailed logs with log rotation to monitor the documentation process.
-
Configuration Flexibility: Customize settings via
config.json
and environment variables. -
Documentation Report: Generates a Markdown report with all generated documentation and a dynamically generated Table of Contents.
-
Unified Badge Function: Generates badges for Cyclomatic Complexity, Halstead Metrics (Volume, Difficulty, Effort), and Maintainability Index.
-
Compact Badge Style: Uses
flat-square
style for badges. -
Dynamic Thresholds: Customizable thresholds for different metrics.
-
Enhanced
generate_documentation_report
: Integrates badge generation into the report. -
Markdown Structure: Uses tables for readability.
-
Environment-Based Thresholds: Fetches thresholds from environment variables.
-
Asynchronous File Writing: Uses
aiofiles
for non-blocking operations. -
Comprehensive Scoring: Calculates maximum complexity across functions and methods.
-
Robust Error Management: Handles missing Halstead metrics and logs errors.
-
Flexibility and Customization: Dynamic thresholds and compact badge styles.
- Python
- JavaScript
- TypeScript
- Go
- C++
- Java
- HTML
- CSS
- Python 3.9+
- Node.js (for JavaScript/TypeScript handlers)
- OpenAI API Key or Azure OpenAI Credentials
- Git (for cloning the repository)
git clone https://github.com/yourusername/yourrepo.git
cd yourrepo
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Navigate to the scripts
directory and install dependencies:
cd scripts
npm install
cd ..
Create a .env
file in the root directory:
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key
AZURE_OPENAI_API_KEY=your_azure_openai_api_key
ENDPOINT_URL=your_azure_endpoint_url
DEPLOYMENT_NAME=your_azure_deployment_name
# Other Configurations
MODEL_NAME=gpt-4
Create a config.json
file:
{
"project_info": "This project is an AI-driven documentation generator.",
"style_guidelines": "Follow Google Python Style Guide.",
"excluded_dirs": ["tests", "docs"],
"excluded_files": ["setup.py", "manage.py"],
"skip_types": [".json", ".md", ".txt", ".csv", ".lock"]
}
python3 main.py /path/to/your/project -c config.json --use-azure --concurrency 3 -o documentation_report.md
/path/to/your/project
: Path to the codebase.-c config.json
: Path to the configuration file.--use-azure
: Use Azure OpenAI.--concurrency 3
: Number of concurrent API requests.-o documentation_report.md
: Output file for the report.
python3 main.py ./my_project -c config.json --use-azure --concurrency 5 -o docs_output.md
- Configuration: Reads from
config.json
and environment variables. - File Collection: Traverses the project directory.
- Code Structure Extraction: Extracts structures using handlers.
- Documentation Generation: Uses AI to generate documentation.
- Docstring Insertion: Inserts docstrings into source code.
- Validation: Validates code with syntax checks.
- Reporting: Compiles Markdown report with badges.
Modify function_schema.json
to fit your needs.
Modify format_function_docstring
in utils.py
.
- Create a Language Handler: Inherit from
BaseHandler
. - Implement Methods:
extract_structure
andinsert_docstrings
. - Update
LANGUAGE_MAPPING
: Add file extensions inutils.py
.
-
Fork the Repository
-
Create a Feature Branch
git checkout -b feature/YourFeature
-
Commit Your Changes
git commit -m "Add YourFeature"
-
Push to the Branch
git push origin feature/YourFeature
-
Open a Pull Request
This project is licensed under the MIT License.
For questions or support, contact hperkin4@asu.edu.
You can also reach out through:
Enhance your codebase documentation effortlessly with AI-driven precision.