Development Environment Setup¶
This guide explains how to set up the development environment for contributing to Python Project Template.
The project provides a Makefile to simplify common development tasks.
Prerequisites¶
Install the following tools before starting development.
| Tool | Version | Description |
|---|---|---|
| Python | >=3.14 | Python programming language |
| uv | >=0.10 | Python package and project manager |
Clone the repository:
Project Structure¶
The repository is organized as follows:
python-project-template/
├─ src/ # Python package source code
├─ tests/ # Test suite
├─ docs/ # Documentation sources (MkDocs)
├─ config/ # Example configuration files (optional)
├─ .vscode/ # VSCode settings (optional)
├─ .github/ # GitHub workflows and repository settings
├─ pyproject.toml # Project configuration and dependencies
├─ Makefile # Development commands
├─ mkdocs.yml # MkDocs configuration
├─ uv.lock # Locked dependency versions
└─ README.md # Project overview
Installing Dependencies¶
Install the project dependencies and set up the local development environment:
This command performs the following:
- Installs all dependencies via
uv. - Registers pre-commit hooks to automate code quality checks.
- Configures the Git commit message template.
Linting and Testing¶
Format Code¶
Format the code:
Lint Code¶
Run linting and static type checking:
Run Tests¶
Run the test suite:
Verify Code¶
Run all verification steps (formatting, linting, and tests):
Documentation¶
Lint Documentation¶
Run documentation linting:
Build Documentation¶
Build the documentation:
Start the Documentation Server¶
This project uses MkDocs to generate the HTML documentation and
mkdocstrings-python to generate the Python API reference.
Start the documentation server with:
Open the documentation in your browser at http://localhost:8000.