# Python Project Boilerplate

Start new Python applications quickly with a minimal, well-structured foundation.

## Features

- Python package layout under `src/`
- `pyproject.toml` with placeholders for metadata and dependencies
- Ruff formatting & linting
- Nox automation for format, lint, type-check, tests, docs, build
- MkDocs configured for documentation
- Ready-made dev container configuration

## Quick Start

```bash
# clone the template
# replace <your-org> and <project-name>
git clone https://example.com/<your-org>/<project-name>.git
cd <project-name>

# optional: rename package directory under src/

# create virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# run quality checks
nox -s format lint typecheck tests

# run the sample CLI
python -m boilerplate
```

## Replace Placeholders

Update the following files with real project information:

- `pyproject.toml`
- `mkdocs.yml`
- `docs/index.md`
- `README.md`

## Documentation

```bash
nox -s docs
nox -s serve_docs
```

## Tests

Simple placeholder tests live in `tests/`.
Run them with `nox -s tests` or `pytest`.