🚀 Quick Start Guide

“Give me six hours to chop down a tree and I will spend the first four sharpening the axe.” — Abraham Lincoln

Get up and running with Seedling in under 5 minutes! 🌱 This guide walks you through the essentials so you can start coding instead of configuring.

🧰 Prerequisites

  • Python 3.11+ — Modern language features & type hints

  • Git — Version control (because you will want history)

  • Copier — Template engine (we’ll install it)

  • uv — Fast Python package manager (recommended)

  • Nox — Task automation (recommended)

  • Just — Command runner for shortcuts (optional, but addictive)

📦 Installation

1 — Install Required Tools

# One-stop shop (recommended)
curl -LsSf https://raw.githubusercontent.com/jeffrichley/seedling/main/scripts/install-tools.sh | bash

# Or roll your own
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install copier
uv pip install nox

Install Just (command runner)

  • macOS: brew install just

  • Linux: download binary from releases and add to PATH

  • Windows: choco install just

2 — Generate Your First Project

copier copy https://github.com/jeffrichley/seedling-template.git my-awesome-project

You’ll be prompted for config:

project_name [My Awesome Project]: My Data Science Tool
project_slug [my_awesome_project]: my_data_science_tool
project_description [A modern Python project built with best practices]: A powerful data science toolkit
author_name [Your Name]: Jane Doe
author_email [your.name@example.com]: jane.doe@example.com
github_username [yourusername]: janedoe
license (MIT, Apache-2.0, GPL-3.0, BSD-3-Clause) [MIT]: MIT
python_versions [3.11,3.12]: 3.11,3.12
coverage_threshold [80]: 85

4 — Set Up Development Environment

uv sync            # Install dependencies
pre-commit install # Activate hooks
just quality       # Run initial quality sweep

5 — Start Developing!

nox -s tests   # via Nox (recommended)
just test      # via Just
just lint      # Format & lint
just docs      # Build docs

🎯 What Just Happened?

  1. Project Structure — Ready-to-go Python scaffolding

  2. Dependencies — Installed & configured

  3. Quality Tools — Hooks, linting, tests in place

  4. CI/CD — GitHub Actions locked & loaded

  5. Docs — Sphinx site bootstrapped

📁 Your New Project Structure

my-awesome-project/
├── src/my_data_science_tool/    # Your package code
├── tests/                       # Unit ▸ Integration ▸ E2E
├── docs/                        # Documentation
├── .github/                     # CI workflows
├── pyproject.toml               # Config central
├── .pre-commit-config.yaml      # Quality rules
├── noxfile.py                   # Automation scripts
├── justfile                     # Command shortcuts
└── README.md                    # Project overview

🛠️ Available Commands

Using Nox

nox -s tests        # Run tests
nox -s lint         # Lint code
nox -s type_check   # Type checking
nox -s docs         # Build docs
nox -s lint type_check docs # All checks

Using Just

just test       # Tests
just lint       # Lint
just type-check # Type checking
just docs       # Docs
just quality    # All checks

Using uv Directly

uv sync
uv run pytest
uv run black src tests
uv run ruff check src tests --fix
uv run mypy src tests

🎯 What the Template Provides

✅ Automatically Included

  • Python deps: Black, Ruff, MyPy, pytest, Sphinx, etc.

  • Pre-commit hooks

  • Nox automation

  • Just shortcuts

  • GitHub Actions CI/CD

  • Complete test scaffold

  • Docs with Sphinx + Furo

🔧 What You Install

  • Copier — Project generator

  • uv — Dependency manager

  • Nox — Task automation

  • Just — Shortcuts (optional)

🌱 Next Steps

  • Read the docs — Peek into the docs/ folder

  • Customize configs — Edit pyproject.toml & friends

  • Add code — Start in src/my_data_science_tool/

  • Write tests — Keep tests/ healthy

  • Deploy — Push to GitHub; CI/CD takes it from there

For more details, see the 📦 Installation Guide and ⚙️ Configuration Guide guides.