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.11	Python programming language
uv	>=0.10	Python package and project manager

Clone the repository:

git clone https://github.com/oqtopus-team/oqtopus-util.git
cd oqtopus-util

Project Structure¶

The repository is organized as follows:

oqtopus-util/
├─ src/           # Python package source code
├─ tests/         # Test suite
├─ docs/          # Documentation sources (MkDocs)
├─ .vscode/       # VSCode settings
├─ .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:

make install

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:

make format

Lint Code¶

Run linting and static type checking:

make lint

Run Tests¶

Run the test suite:

make test

Verify Code¶

Run all verification steps (formatting, linting, and tests):

make verify

Documentation¶

Lint Documentation¶

Run documentation linting:

make docs-lint

Build Documentation¶

Build the documentation:

make docs-build

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:

make docs-serve

Open the documentation in your browser at http://localhost:8000.