From a43021055c1ff9a8929ffe18804e4fa6ebb1cda2 Mon Sep 17 00:00:00 2001
From: stef <steba92@hotmail.com>
Date: Sun, 25 May 2025 08:45:02 +0100
Subject: [PATCH] docs: improve README

---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 44 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 063a418..e9f02db 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,50 @@
 # Template Python Repository
 
-A minimal, conservative Python project template configured with:
+This repository provides a minimal yet opinionated starting point for Python
+projects. It bundles common development tools and a GitHub Actions workflow so
+you can focus on writing code rather than configuring your environment.
+
+## Features
+
 - **Poetry** for dependency management
-- **Ruff** for linting & formatting
-- **Pyright** for type-checking
-- **Pytest** for testing
-- **Wily** for code complexity analysis
-- **GitHub Actions** for CI (lint, test, complexity check)
+- **Ruff** for formatting and linting
+- **Pyright** for static type checking
+- **Pytest** for unit tests
+- **Wily** for complexity metrics
+- **GitHub Actions** for CI (lint, tests and complexity analysis)
 - **Makefile** with handy developer commands
 
-## Usage
+## Getting Started
+
+1. **Replace** all occurrences of `template` with your project name. This is
+   primarily in `pyproject.toml` and the `template/` package directory.
+2. **Install dependencies**:
+
+   ```bash
+   poetry install
+   ```
+3. **Run code checks** (formatting, linting and type checking):
+
+   ```bash
+   make check
+   ```
+4. **Execute tests**:
+
+   ```bash
+   make test
+   ```
+
+## Common Makefile Commands
+
+- **Format code**: `make format`
+- **Run linter**: `make lint`
+- **Auto-fix lint issues**: `make lint-fix`
+- **Type check**: `make typecheck`
+- **Watch tests**: `make watch`
+- **Show all commands**: `make help`
+
+## Continuous Integration
+
+The included GitHub Actions workflow runs linting, type checks, unit tests and
+complexity analysis for every push and pull request.
 
-- **Replace** all occurrences of "`template`" (e.g., in `pyproject.toml` and the top-level `template` directory) with your project name.
-- **Install dependencies**: `poetry install`
-- **Run linting**: `make lint`
-- **Run type checks**: `make typecheck`
-- **Run tests**: `make test`
-- **View additional commands**: `make help`