claudi
61aa33633c
- Created architecture documentation outlining high-level design, module organization, data flow, security model, performance considerations, testing strategy, and deployment architecture. - Added pyproject.toml for project metadata and dependencies management. - Introduced requirements files for development and production dependencies. - Set up testing configuration with pytest and tox. - Established basic directory structure for source code and tests, including __init__.py files. - Implemented a sample web application (index.html) for drag-and-drop functionality. - Configured VS Code workspace settings for Python development.
231 lines
5.2 KiB
Markdown
231 lines
5.2 KiB
Markdown
# Quick Start Guide
|
|
|
|
## Project Setup (5 minutes)
|
|
|
|
### 1. Open in VS Code
|
|
|
|
```bash
|
|
# Option A: Open the workspace file directly
|
|
code webdrop_bridge.code-workspace
|
|
|
|
# Option B: Open the folder
|
|
code .
|
|
```
|
|
|
|
### 2. Install Dependencies
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
|
|
# Activate virtual environment
|
|
source venv/bin/activate # macOS/Linux
|
|
# venv\Scripts\activate # Windows
|
|
|
|
# Install development dependencies
|
|
pip install -r requirements-dev.txt
|
|
```
|
|
|
|
### 3. Verify Installation
|
|
|
|
```bash
|
|
# Run project structure tests
|
|
pytest tests/unit/test_project_structure.py -v
|
|
|
|
# Expected output:
|
|
# test_project_structure.py::test_project_structure PASSED
|
|
# test_project_structure.py::test_essential_files PASSED
|
|
# test_project_structure.py::test_python_package_structure PASSED
|
|
```
|
|
|
|
## Project Structure Overview
|
|
|
|
```
|
|
webdrop-bridge/
|
|
│
|
|
├── src/webdrop_bridge/ ← Main application code
|
|
│ ├── core/ ← Business logic (validator, drag interceptor)
|
|
│ ├── ui/ ← UI components (main window, widgets)
|
|
│ └── utils/ ← Utilities (logging, helpers)
|
|
│
|
|
├── tests/ ← Test suite
|
|
│ ├── unit/ ← Unit tests
|
|
│ ├── integration/ ← Integration tests
|
|
│ └── fixtures/ ← Test data
|
|
│
|
|
├── build/ ← Build automation
|
|
│ ├── windows/ ← Windows-specific
|
|
│ ├── macos/ ← macOS-specific
|
|
│ └── scripts/ ← Build scripts
|
|
│
|
|
├── docs/ ← Documentation
|
|
│ └── ARCHITECTURE.md ← Architecture guide
|
|
│
|
|
├── webapp/ ← Embedded web application
|
|
│ └── index.html ← Test drag-drop page
|
|
│
|
|
├── DEVELOPMENT_PLAN.md ← Detailed roadmap
|
|
├── README.md ← User documentation
|
|
├── CONTRIBUTING.md ← Contributing guidelines
|
|
└── Makefile ← Convenience commands
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Phase 1: Core Components (Now)
|
|
|
|
The project is structured to begin implementing core components. Start with:
|
|
|
|
1. **Configuration System** (`src/webdrop_bridge/config.py`)
|
|
- Environment-based configuration
|
|
- Validation and defaults
|
|
|
|
2. **Path Validator** (`src/webdrop_bridge/core/validator.py`)
|
|
- Whitelist-based path validation
|
|
- Security checks
|
|
|
|
3. **Drag Interceptor** (`src/webdrop_bridge/core/drag_interceptor.py`)
|
|
- Qt drag-and-drop handling
|
|
- Text-to-file conversion
|
|
|
|
4. **Main Window** (`src/webdrop_bridge/ui/main_window.py`)
|
|
- Qt application window
|
|
- WebEngine integration
|
|
|
|
See [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md#phase-1-foundation-weeks-1-4) for detailed specifications.
|
|
|
|
## Common Tasks
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
pytest tests -v
|
|
|
|
# With coverage
|
|
pytest --cov=src/webdrop_bridge
|
|
|
|
# Specific test type
|
|
pytest tests/unit/ -v # Unit tests
|
|
pytest tests/integration/ -v # Integration tests
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Format code
|
|
tox -e format
|
|
|
|
# Check formatting
|
|
tox -e lint
|
|
|
|
# Type checking
|
|
tox -e type
|
|
|
|
# All checks at once
|
|
tox
|
|
```
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Windows MSI
|
|
python build/scripts/build_windows.py
|
|
|
|
# macOS DMG
|
|
bash build/scripts/build_macos.sh
|
|
```
|
|
|
|
### Documentation
|
|
|
|
```bash
|
|
# Build Sphinx docs
|
|
tox -e docs
|
|
|
|
# View docs
|
|
open docs/_build/html/index.html # macOS
|
|
start docs\_build\html\index.html # Windows
|
|
```
|
|
|
|
## Using Makefile (Convenience)
|
|
|
|
```bash
|
|
# List all commands
|
|
make help
|
|
|
|
# Install dependencies
|
|
make install-dev
|
|
|
|
# Run tests
|
|
make test
|
|
|
|
# Code quality
|
|
make lint
|
|
make format
|
|
make type
|
|
|
|
# Build
|
|
make build-windows
|
|
make build-macos
|
|
|
|
# Clean
|
|
make clean
|
|
```
|
|
|
|
## VS Code Tips
|
|
|
|
### Debugging
|
|
|
|
1. **Set breakpoint**: Click line number
|
|
2. **Start debugging**: F5 (or Run → Run Without Debugging)
|
|
3. **Step over**: F10
|
|
4. **Step into**: F11
|
|
|
|
Configurations available in `.vscode/launch.json`:
|
|
- Python: Current File
|
|
- WebDrop Bridge (main application)
|
|
|
|
### Testing in VS Code
|
|
|
|
1. **Open test file**: `tests/unit/test_project_structure.py`
|
|
2. **Run test**: Click "Run Test" above test function
|
|
3. **Debug test**: Click "Debug Test"
|
|
|
|
### Recommended Extensions
|
|
|
|
- Python (ms-python.python)
|
|
- Pylance (ms-python.vscode-pylance)
|
|
- Black Formatter (ms-python.black-formatter)
|
|
- Ruff (charliermarsh.ruff)
|
|
|
|
## Configuration
|
|
|
|
Create `.env` file from template:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit as needed:
|
|
- `WEBAPP_URL` - Web app location
|
|
- `ALLOWED_ROOTS` - Whitelisted directories
|
|
- `LOG_LEVEL` - DEBUG, INFO, WARNING, ERROR
|
|
|
|
## Next Steps
|
|
|
|
1. **Read** [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md) for detailed roadmap
|
|
2. **Review** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for design decisions
|
|
3. **Start** with Phase 1 core components
|
|
4. **Write tests** for new code (TDD approach)
|
|
5. **Follow** guidelines in [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
|
|
## Getting Help
|
|
|
|
- 📖 **Documentation**: See README.md, DEVELOPMENT_PLAN.md, docs/
|
|
- 🐛 **Issues**: GitHub Issues tracker
|
|
- 💬 **Questions**: GitHub Discussions
|
|
- 🤝 **Contributing**: See CONTRIBUTING.md
|
|
|
|
---
|
|
|
|
**Ready to start?** → Open `DEVELOPMENT_PLAN.md` Phase 1 section
|