(Feat): Initial Commit.

SETUP_GUIDE.md

@@ -0,0 +1,228 @@
+# Setup and Verification Guide
+
+This guide will help you set up the development environment and verify that everything is working correctly.
+
+## Prerequisites
+
+- Python 3.10 or higher
+- pip (Python package installer)
+- git
+
+## Quick Start
+
+### 1. Setup Development Environment
+
+```bash
+# Navigate to the project directory
+cd /home/zanewalker/Development/Programming/PythonProjects/Libraries/fastapi-route-loader
+
+# Run the setup script
+bash scripts/setup.sh
+
+# Or manually:
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+### 2. Verify Installation
+
+After setup, verify everything is working:
+
+```bash
+# Activate virtual environment (if not already activated)
+source .venv/bin/activate
+
+# Run verification script
+bash scripts/verify.sh
+```
+
+## Manual Verification Steps
+
+If you prefer to run checks individually:
+
+### Run Tests
+
+```bash
+# Run all tests with coverage
+pytest
+
+# Run specific test file
+pytest tests/test_container.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Check Code Quality
+
+```bash
+# Run ruff linter
+ruff check src/ tests/ examples/
+
+# Auto-fix issues
+ruff check --fix src/ tests/ examples/
+
+# Check formatting
+ruff format --check src/ tests/ examples/
+
+# Format code
+ruff format src/ tests/ examples/
+```
+
+### Type Checking
+
+```bash
+# Run pyright on source code
+pyright src/
+
+# Check specific file
+pyright src/fastapi_route_loader/container.py
+```
+
+## Project Structure
+
+```
+fastapi-route-loader/
+├── src/
+│   └── fastapi_route_loader/
+│       ├── __init__.py          # Package exports
+│       ├── container.py         # RouterContainer class
+│       ├── events.py            # Event system
+│       ├── loader.py            # Router loader
+│       └── py.typed             # Type hint marker
+├── tests/
+│   ├── __init__.py
+│   ├── test_container.py        # Container tests
+│   ├── test_events.py           # Event system tests
+│   ├── test_loader.py           # Loader tests
+│   └── test_integration.py      # Integration tests
+├── examples/
+│   ├── basic_usage.py           # Basic usage example
+│   └── event_handling.py        # Event handling example
+├── scripts/
+│   ├── setup.sh                 # Setup script
+│   └── verify.sh                # Verification script
+├── pyproject.toml               # Project configuration
+├── README.md                    # Main documentation
+├── CONTRIBUTING.md              # Contribution guidelines
+├── LICENSE                      # MIT License
+└── .python-version              # Python version (3.10)
+```
+
+## Configuration Files
+
+### pyproject.toml
+
+The project uses:
+- **Build System**: Hatchling
+- **Linter**: Ruff with strict rules
+- **Type Checker**: Pyright in strict mode
+- **Test Framework**: pytest with coverage
+- **Python Support**: 3.10+
+
+### Ruff Configuration
+
+Strict linting with comprehensive rule sets including:
+- pycodestyle (E, W)
+- pyflakes (F)
+- isort (I)
+- flake8-bugbear (B)
+- pyupgrade (UP)
+- And many more...
+
+### Pyright Configuration
+
+Strict type checking with:
+- Type checking mode: strict
+- Python version: 3.10
+- Some unknowns allowed for external dependencies
+
+## Running Examples
+
+```bash
+# Activate virtual environment
+source .venv/bin/activate
+
+# Run basic usage example
+python examples/basic_usage.py
+
+# Run event handling example
+python examples/event_handling.py
+```
+
+## Troubleshooting
+
+### Virtual Environment Issues
+
+If you encounter issues with the virtual environment:
+
+```bash
+# Remove existing venv
+rm -rf .venv
+
+# Create new venv
+python3 -m venv .venv
+
+# Activate and reinstall
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+### Import Errors
+
+If you get import errors:
+
+```bash
+# Ensure package is installed in editable mode
+pip install -e .
+
+# Or with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Test Failures
+
+If tests fail:
+
+```bash
+# Run tests with verbose output
+pytest -v
+
+# Run specific failing test
+pytest tests/test_container.py::TestRouterContainer::test_add_router -v
+
+# Check for missing dependencies
+pip install pytest pytest-cov pytest-asyncio httpx
+```
+
+### Type Checking Errors
+
+The library code is designed to pass strict type checking. However, you may see warnings about:
+- Unknown types from FastAPI (expected when FastAPI is not installed)
+- Test fixtures (tmp_path, etc.) - these are ignored in test files
+
+To verify the source code only:
+
+```bash
+pyright src/
+```
+
+## Next Steps
+
+1. Read the [README.md](README.md) for usage examples
+2. Check [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
+3. Explore the [examples/](examples/) directory
+4. Run the tests to see the library in action
+
+## Support
+
+If you encounter any issues:
+1. Check this guide
+2. Review the README.md
+3. Check existing GitHub issues
+4. Create a new issue with details
+
+Happy coding! 🚀