claudi
87884935c9
Some checks are pending
Tests & Quality Checks / Test on Python 3.11 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.10 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-2 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-2 (push) Waiting to run
Tests & Quality Checks / Build Artifacts (push) Blocked by required conditions
Tests & Quality Checks / Build Artifacts-1 (push) Blocked by required conditions
325 lines
7.2 KiB
Markdown
325 lines
7.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
|
|
```
|
|
|
|
## 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
|
|
```
|
|
|
|
### Running Integration Tests
|
|
|
|
```bash
|
|
pytest tests/integration/ -v
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Format code
|
|
tox -e format
|
|
|
|
# Check formatting
|
|
tox -e lint
|
|
|
|
# Type checking
|
|
tox -e type
|
|
|
|
# All checks at once
|
|
tox
|
|
```
|
|
|
|
### Installing from Release (wget)
|
|
|
|
Download pre-built installers from Forgejo releases using **wget**, **package managers**, or **automated scripts** (useful for enterprise deployments, automated scripts, or initial setup before the built-in update mechanism):
|
|
|
|
#### Package Manager (Easiest)
|
|
|
|
**Windows (Chocolatey)**
|
|
|
|
```powershell
|
|
# Install
|
|
choco install webdrop-bridge
|
|
|
|
# Upgrade to latest
|
|
choco upgrade webdrop-bridge
|
|
|
|
# Uninstall
|
|
choco uninstall webdrop-bridge
|
|
```
|
|
|
|
**macOS (Homebrew with custom tap)**
|
|
|
|
```bash
|
|
# Add tap (one-time setup)
|
|
brew tap HIM-public/webdrop-bridge https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git
|
|
|
|
# Install
|
|
brew install webdrop-bridge
|
|
|
|
# Upgrade
|
|
brew upgrade webdrop-bridge
|
|
|
|
# Uninstall
|
|
brew uninstall webdrop-bridge
|
|
```
|
|
|
|
For more package manager details and internal hosting options, see [docs/PACKAGE_MANAGER_SUPPORT.md](../docs/PACKAGE_MANAGER_SUPPORT.md)
|
|
|
|
#### Simplest: Direct wget (if you know the version)
|
|
|
|
```bash
|
|
# Replace VERSION with release tag (e.g., v0.8.0)
|
|
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/VERSION/WebDropBridge_Setup.msi
|
|
|
|
# Real example - download v0.8.0 MSI
|
|
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi
|
|
|
|
# macOS - download v0.8.0 DMG
|
|
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg
|
|
```
|
|
|
|
#### Windows (PowerShell) - Full Control Script
|
|
|
|
```powershell
|
|
# Download latest release
|
|
.\build\scripts\download_release.ps1
|
|
|
|
# Download to specific directory
|
|
.\build\scripts\download_release.ps1 -OutputDir "C:\Installers"
|
|
|
|
# Download specific version
|
|
.\build\scripts\download_release.ps1 -Version "0.8.0"
|
|
|
|
# Skip checksum verification
|
|
.\build\scripts\download_release.ps1 -Verify $false
|
|
```
|
|
|
|
**Prerequisites**: `wget` (install via `choco install wget` or `winget install GNU.Wget`)
|
|
|
|
#### macOS / Linux (Bash) - Full Control Script
|
|
|
|
```bash
|
|
# Download latest release to current directory
|
|
./build/scripts/download_release.sh
|
|
|
|
# Download to specific directory
|
|
./build/scripts/download_release.sh latest ~/Downloads
|
|
|
|
# Download specific version
|
|
./build/scripts/download_release.sh 0.8.0
|
|
|
|
# Skip checksum verification
|
|
./build/scripts/download_release.sh latest --no-verify
|
|
```
|
|
|
|
**Prerequisites**: `wget` (install via `brew install wget` on macOS or `apt-get install wget` on Linux)
|
|
|
|
#### Alternative Methods
|
|
|
|
**With checksum verification (grep/cut, no jq required):**
|
|
|
|
```bash
|
|
# Get latest and download with automatic checksum verification
|
|
wget -qO- https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest | \
|
|
grep -o '"browser_download_url":"[^"]*\.\(msi\|dmg\)"' | head -1 | cut -d'"' -f4 | \
|
|
xargs wget -O installer.msi
|
|
```
|
|
|
|
**Via web browser:**
|
|
|
|
Simply visit https://git.him-tools.de/HIM-public/webdrop-bridge/releases and download directly
|
|
|
|
### Building from Source
|
|
|
|
```bash
|
|
# Windows MSI
|
|
python build/scripts/build_windows.py --msi
|
|
|
|
# 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
|
|
|
|
### To Run the Application
|
|
```bash
|
|
# Run the full application (requires config)
|
|
python -m webdrop_bridge.main
|
|
```
|
|
|
|
### To Run Tests
|
|
```bash
|
|
# Run all tests
|
|
pytest tests -v
|
|
|
|
# Run with coverage
|
|
pytest --cov=src/webdrop_bridge tests
|
|
|
|
# Run specific test file
|
|
pytest tests/unit/test_config.py -v
|
|
```
|
|
|
|
### To Contribute
|
|
**Review** [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
|
|
## Getting Help
|
|
|
|
- 📖 **Documentation**: See README.md, DEVELOPMENT_PLAN.md, docs/
|
|
|
|
---
|
|
|