Development Setup¶

Complete guide for setting up a development environment.

Prerequisites¶

Python 3.8 or higher
Git
A code editor (VS Code, PyCharm, etc.)

Fork and Clone¶

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/pib3.git
cd pib3

# Add upstream remote
git remote add upstream https://github.com/mamrehn/pib3.git

Virtual Environment¶

Linux / macOS¶

python -m venv venv
source venv/bin/activate

Windows¶

python -m venv venv
venv\Scripts\activate

Install Dependencies¶

# Install in editable mode with all dev dependencies
pip install -e ".[dev]"

# Or install specific extras
pip install -e ".[image,viz,robot,dev]"

Verify Installation¶

# Check import works
python -c "import pib3; print(pib3.__version__)"

# Run tests
pytest

# Run with coverage
pytest --cov=pib3 --cov-report=html

Project Structure¶

pib3/
├── pib3/              # Source code
│   ├── __init__.py      # Public API
│   ├── config.py        # Configuration classes
│   ├── types.py         # Core types
│   ├── image.py         # Image processing
│   ├── trajectory.py    # Trajectory generation
│   ├── backends/        # Robot backends
│   └── resources/       # Bundled assets (URDF, STL)
├── tests/               # Test files
├── docs/                # Documentation
├── pyproject.toml       # Package configuration
└── CLAUDE.md            # AI assistant instructions

Development Workflow¶

1. Create a Branch¶

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/your-feature-name

2. Make Changes¶

Edit code, add tests, update documentation as needed.

3. Run Tests¶

# Run all tests
pytest

# Run specific test file
pytest tests/test_trajectory.py

# Run with verbose output
pytest -v

# Run tests matching a pattern
pytest -k "test_sketch"

4. Check Code Quality¶

# Format code (if using black)
black pib3 tests

# Check types (if using mypy)
mypy pib3

# Lint (if using ruff)
ruff check pib3

5. Commit and Push¶

git add .
git commit -m "feat: Add your feature description"
git push origin feature/your-feature-name

6. Submit Pull Request¶

Go to GitHub and create a pull request from your branch.

Running Documentation Locally¶

# Install docs dependencies
pip install mkdocs-material mkdocstrings[python]

# Serve documentation locally
mkdocs serve

# Open http://localhost:8000 in browser

Testing with Hardware¶

Webots Simulator¶

Install Webots
Open a PIB world file
Set controller to your test script

Real Robot¶

# Test connection (requires robot on network)
python -c "
from pib3 import Robot
robot = Robot(host='172.26.34.149', timeout=5.0)
try:
    robot.connect()
    print('Connected!')
    robot.disconnect()
except Exception as e:
    print(f'Connection failed: {e}')
"

Common Tasks¶

Adding a New Feature¶

Create feature branch
Write tests first (TDD encouraged)
Implement feature
Add documentation
Submit PR

Fixing a Bug¶

Write a failing test that reproduces the bug
Fix the bug
Verify test passes
Submit PR with test and fix

Updating Documentation¶

# Edit docs/*.md files
# Preview changes
mkdocs serve

# Documentation is automatically deployed on merge to main

Regenerating URDF¶

If you modify the Webots proto file:

python -m pib3.tools.proto_converter

Environment Variables¶

Variable	Purpose	Default
`PIB_ROBOT_HOST`	Default robot IP	172.26.34.149
`PIB_ROBOT_PORT`	Default rosbridge port	9090
`PIB_DEBUG`	Enable debug logging	false

Troubleshooting¶

Import Errors¶

# Ensure you're in the virtual environment
which python  # Should show venv path

# Reinstall in editable mode
pip install -e ".[dev]"

Test Failures¶

# Run with verbose output
pytest -v --tb=long

# Run single failing test
pytest tests/test_file.py::test_function -v

Documentation Build Errors¶

# Check mkdocs config
mkdocs build --strict

# Common issue: missing docstring
# Solution: Add docstrings to all public functions