Development Setup¶

Guide for setting up a development environment for project-guide.

Prerequisites¶

Python 3.11 or higher
Git
pip or pipx

Clone the Repository¶

git clone https://github.com/pointmatic/project-guide.git
cd project-guide

Set Up Virtual Environment¶

Using venv¶

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

Using pyenv¶

pyenv virtualenv 3.11 project-guide
pyenv activate project-guide

Install Development Dependencies¶

pip install -e ".[dev,docs]"

This installs: - The package in editable mode - Development dependencies (pytest, pytest-cov, ruff, mypy) - Documentation dependencies (mkdocs-material)

Verify Installation¶

# Check package is installed
project-guide --version

# Run tests
pytest

# Check linting
ruff check .

# Check types
mypy project_guide

Development Workflow¶

1. Create a Branch¶

git switch -c feature/your-feature-name

2. Make Changes¶

Edit files in project_guide/ or tests/

3. Run Tests¶

# Run all tests
pytest

# Run with coverage
pytest --cov=project_guide

# Run specific test file
pytest tests/test_cli.py

# Run specific test
pytest tests/test_cli.py::test_init_command

4. Check Code Quality¶

# Lint code
ruff check .

# Format code
ruff format .

# Type check
mypy project_guide

5. Update Documentation¶

If you changed user-facing functionality:

# Edit documentation
vim docs/site/user-guide/commands.md

# Build and preview
mkdocs serve
# Open http://127.0.0.1:8000

6. Commit Changes¶

git add .
git commit -m "Add feature: description"

Project Structure¶

Main Package¶

project_guide/
├── __init__.py               # Package initialization
├── __main__.py               # CLI entry point
├── cli.py                    # CLI commands implementation
├── config.py                 # Configuration model
├── metadata.py               # Metadata loading and validation
├── render.py                 # Jinja2 template rendering
├── sync.py                   # File synchronization logic
├── exceptions.py             # Custom exception classes
├── version.py                # Version information
└── templates/                # Bundled templates
    └── project-guide/        # Project guide templates
        ├── .metadata.yml     # Mode and artifact definitions
        ├── README.md         # Template README
        ├── developer/        # Developer guide templates
        └── templates/        # Jinja2 templates
            ├── modes/        # Mode templates (*.md)
            ├── artifacts/    # Artifact templates (*.md)
            └── go.md         # Go template

Tests¶

tests/
├── __init__.py
├── test_cli.py               # CLI command tests (~60 tests)
├── test_sync.py              # Sync logic tests (~22 tests)
├── test_integration.py       # Integration tests (~6 tests)
├── test_render.py            # Render tests (~20 tests)
├── test_metadata.py          # Metadata tests (~9 tests)
├── test_config.py            # Configuration tests (~7 tests)
└── test_purge.py             # Purge command tests (~5 tests)

Documentation¶

docs/
└── site/                     # MkDocs documentation
    ├── getting-started.md
    ├── user-guide/
    ├── developer-guide/
    └── about/

Running Tests¶

Basic Test Run¶

pytest

With Coverage Report¶

pytest --cov=project_guide --cov-report=html
open htmlcov/index.html

Verbose Output¶

pytest -v

Stop on First Failure¶

pytest -x

Run Specific Tests¶

# By file
pytest tests/test_cli.py

# By test name
pytest tests/test_cli.py::test_init_command

# By pattern
pytest -k "test_init"

Code Quality Tools¶

Ruff (Linter and Formatter)¶

# Check for issues
ruff check .

# Fix auto-fixable issues
ruff check --fix .

# Format code
ruff format .

Mypy (Type Checker)¶

# Type check
mypy project_guide

# Strict mode
mypy --strict project_guide

Building Documentation¶

Local Development¶

# Serve with live reload
mkdocs serve

# Open http://127.0.0.1:8000

Build Static Site¶

# Build to site/ directory
mkdocs build

# Build with strict mode (fail on warnings)
mkdocs build --strict

Debugging¶

Using pdb¶

Add breakpoint in code:

import pdb; pdb.set_trace()

Run tests:

pytest tests/test_cli.py::test_init_command

Using pytest debugging¶

# Drop into pdb on failure
pytest --pdb

# Drop into pdb on first failure
pytest -x --pdb

Verbose CLI Output¶

# Run CLI with Python for better error messages
python -m project_guide init

Common Tasks¶

Add a New Command¶

Add command function in project_guide/cli.py
Add tests in tests/test_cli.py
Update documentation in docs/site/user-guide/commands.md
Run tests and linters

Add a New Mode¶

Create a mode template in project_guide/templates/project-guide/templates/modes/
Add the mode to .metadata.yml in project_guide/templates/project-guide/
Test rendering with project-guide init and select the new mode
Verify the parametrized test in test_render.py picks up the new mode
Document changes in CHANGELOG.md

Update a Template¶

Edit the template in project_guide/templates/project-guide/templates/
Test with project-guide init followed by mode selection to verify rendering
Update version in project_guide/version.py if needed
Document changes in CHANGELOG.md

Add a New Artifact¶

Create an artifact template in project_guide/templates/project-guide/templates/artifacts/
Add the artifact to .metadata.yml
Add tests for the new artifact
Update documentation

Troubleshooting¶

Import Errors¶

Ensure package is installed in editable mode:

pip install -e .

Test Failures¶

Check if dependencies are up to date:

pip install --upgrade -e ".[dev,docs]"

Type Check Errors¶

Ignore specific errors if needed:

# type: ignore[error-code]

Next Steps¶

Contributing Guide - Contribution guidelines
Testing Guide - Detailed testing information