ModuFlow Development Guide

This document provides information for developers who want to contribute to ModuFlow.

Project Structure

moduflow/
├── moduflow/                # Main package directory
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Entry point for running as module
│   ├── cli/                 # CLI section
│   │   ├── __init__.py      # CLI package initialization
│   │   ├── main.py          # CLI entry point
│   │   └── commands.py      # CLI commands implementation
│   ├── core/                # Core functionality section
│   │   ├── __init__.py      # Core package initialization 
│   │   ├── config.py        # Configuration handling
│   │   ├── paths.py         # Path management
│   │   └── exceptions.py    # Custom exceptions
│   ├── handlers/            # File and operations handlers section
│   │   ├── __init__.py      # Handlers package initialization
│   │   ├── yaml_handler.py  # YAML file handling
│   │   ├── file_handler.py  # File operations
│   │   └── section_handler.py # Section management
│   ├── compilers/           # Compilation section
│   │   ├── __init__.py      # Compilers package initialization
│   │   ├── section.py       # Section compilation
│   │   └── project.py       # Project compilation
│   ├── prompts/             # AI prompts section
│   │   ├── __init__.py      # Prompts package initialization
│   │   └── templates.py     # Prompt templates
│   └── utils/               # Utilities section
│       ├── __init__.py      # Utils package initialization
│       └── helpers.py       # Helper functions
├── tests/                   # Test directory
├── docs/                    # Documentation directory
└── ...                      # Other project files

Development Setup

Clone the repository:

git clone https://github.com/moduflow/moduflow.git
cd moduflow

Create a virtual environment:

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

Install development dependencies:
```
pip install -e ".[dev]"
```

Branch Strategy

The project uses a branch-based development workflow:

master - Main stable branch
cli - Branch for CLI development
core - Branch for core functionality
handlers - Branch for file and section handlers
compilers - Branch for compilation functionality
prompts - Branch for AI prompt generation

When working on a feature:

Create a branch from master or the appropriate section branch
Implement and test your changes
Create a pull request targeting the appropriate section branch
After review, the section branch will be merged into master

Testing

Run the tests with pytest:

pytest

Add new tests in the tests/ directory, following the same structure as the main package.

Code Style

This project follows PEP 8 style guidelines with a few exceptions. We use:

Black for code formatting
isort for import sorting
flake8 for linting

You can run these tools with:

black moduflow tests
isort moduflow tests
flake8 moduflow tests

Documentation

Documentation is written in Markdown and stored in the docs/ directory.

To build the documentation:

cd docs
mkdocs build

To serve the documentation locally:

cd docs
mkdocs serve

Release Process

Update version in:
- pyproject.toml
- setup.cfg
- moduflow/__init__.py
Update the CHANGELOG.md
Create a release commit:
```
git commit -am "Release vX.Y.Z"
```
Tag the release:
```
git tag vX.Y.Z
```
Push to GitHub:
```
git push origin master --tags
```

Build and upload to PyPI:

python -m build
python -m twine upload dist/*

Adding New Commands

Create a new command function in moduflow/cli/commands.py
Add the command to the CLI group in moduflow/cli/main.py
Add tests for the command in tests/test_cli.py
Update the documentation in docs/usage.md

Working with Sections

Sections are the core concept of ModuFlow. When adding functionality related to sections:

Consider which component it belongs to (core, handlers, compilers, etc.)
Add appropriate tests
Update documentation

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a Pull Request

Please make sure your code passes all tests and follows the style guidelines.