🌱 Rhiza

Reusable Configuration Templates for Modern Python Projects

ῥίζα (ree-ZAH) — Ancient Greek for "root"

🤔 The Problem

Setting up a new Python project is time-consuming:

⚙️ Configuring CI/CD pipelines
🧪 Setting up testing frameworks
📝 Creating linting and formatting rules
📚 Configuring documentation generation
🔧 Establishing development workflows
🐳 Setting up dev containers

Result: Hours of configuration before writing actual code

💡 The Solution: Rhiza

A curated collection of battle-tested templates that:

✅ Save time on project setup ✅ Enforce best practices ✅ Maintain consistency across projects ✅ Stay up-to-date automatically ✅ Support multiple Python versions (3.11-3.14)

✨ Key Features

### 🚀 Automation - GitHub Actions workflows - Pre-commit hooks - Automated releases - Version bumping ### 🧪 Testing - pytest configuration - CI test matrix - Code coverage - Documentation tests

### 📚 Documentation - API docs with pdoc - Companion book with minibook - Presentation slides with Marp - Interactive notebooks ### 🔧 Developer Experience - Dev containers - VS Code integration - GitHub Codespaces ready - SSH agent forwarding

📁 Available Templates

🌱 Core Project Configuration

.gitignore — Python project defaults
.editorconfig — Consistent coding standards
ruff.toml — Linting and formatting
pytest.ini — Testing framework
Makefile — Common development tasks
CODE_OF_CONDUCT.md & CONTRIBUTING.md

📁 Available Templates (cont.)

🔧 Developer Experience

.devcontainer/ — VS Code dev containers
.pre-commit-config.yaml — Pre-commit hooks
docker/ — Dockerfile templates

🚀 CI/CD & Automation

.github/workflows/ — GitHub Actions
Automated testing & releases
Documentation generation
Template synchronization

🎯 Quick Start

1. Automated Injection (Recommended)

cd /path/to/your/project
uvx rhiza .

This creates .github/template.yml and syncs templates automatically.

2. Manual Integration

# Clone Rhiza
git clone https://github.com/jebel-quant/rhiza.git /tmp/rhiza

# Copy sync mechanism
cp /tmp/rhiza/.github/template.yml .github/
cp /tmp/rhiza/.rhiza/scripts/sync.sh .rhiza/scripts/

# Sync templates
./.rhiza/scripts/sync.sh

🔄 Template Synchronization

Templates stay up-to-date with Rhiza's latest improvements:

Configuration: `.github/template.yml`

repository: Jebel-Quant/rhiza
ref: v0.7.1

include: |
  .github/workflows/*.yml
  .pre-commit-config.yaml
  ruff.toml
  pytest.ini

exclude: |
  .rhiza/scripts/customisations/*

🔄 Automated Sync Workflow

The sync.yml workflow keeps your project current:

📅 Runs weekly (configurable)
🔄 Fetches latest templates from Rhiza
🔍 Applies only included files
🎯 Respects exclude patterns
📝 Creates pull request with changes
🤖 Fully automated

Manual trigger: GitHub Actions → "Sync Templates" → "Run workflow"

🛠️ Makefile: Your Command Center

make install      # Setup project with uv
make test         # Run pytest test suite
make fmt          # Run pre-commit hooks
make docs         # Generate API documentation
make book         # Build companion book
make presentation # Generate slides from PRESENTATION.md
make marimo       # Launch Marimo notebook server
make bump         # Interactive version bump
make release      # Tag and release

Tip: Run make help to see all available targets

📊 Marimo Integration

Marimo — Modern interactive Python notebooks

make marimo  # Start notebook server

Features

🔄 Reactive execution
🐍 Pure Python (no JSON)
📦 Self-contained dependencies
🎨 Built-in visualizations
💻 VS Code extension support

Notebooks stored in book/marimo/ with inline dependency management.

🚀 Release Workflow

One-Step Publish (Recommended)

make publish
# → Bumps version + creates tag + pushes
# → Triggers release workflow

Two-Step Process

# 1. Bump version
make bump
# → Interactive prompts for patch/minor/major
# → Updates pyproject.toml
# → Commits and pushes changes

# 2. Create release
make release
# → Creates git tag
# → Pushes tag to GitHub
# → Triggers release workflow

Check Status

make release-status
# → Shows workflow run history
# → Shows latest release details

Release Automation

✅ Builds Python package ✅ Creates GitHub release ✅ Publishes to PyPI (if public) ✅ Publishes devcontainer image (optional)

🐳 Dev Container Features

What You Get

🐍 Python 3.14 runtime
⚡ UV package manager
🔧 All project dependencies
🧪 Pre-commit hooks
📊 Marimo integration
🔐 SSH agent forwarding
🚀 Port 8080 forwarding

Usage

VS Code: Reopen in Container Codespaces: Create codespace on GitHub

🔧 Customization

Build Extras

Create .rhiza/scripts/customisations/build-extras.sh:

#!/bin/bash
set -euo pipefail

# Install system dependencies
sudo apt-get update
sudo apt-get install -y graphviz

# Your custom setup here

Runs during: make install, make test, make book, make docs

🎨 Documentation Customization

API Documentation (pdoc)

mkdir -p book/pdoc-templates
# Add custom Jinja2 templates

Companion Book (minibook)

mkdir -p book/minibook-templates
# Create custom.html.jinja2

Presentations (Marp)

Edit PRESENTATION.md and run:

make presentation      # Generate HTML
make presentation-pdf  # Generate PDF
make presentation-serve # Interactive preview

⚙️ Configuration Variables

Control Python versions via repository variables:

`PYTHON_MAX_VERSION`

Default: '3.14'
Tests on 3.11, 3.12, 3.13, 3.14
Set to '3.13' to exclude 3.14

`PYTHON_DEFAULT_VERSION`

Default: '3.14'
Used in release, pre-commit, book workflows
Set to '3.12' for compatibility

Set in: Repository Settings → Secrets and variables → Actions → Variables

🔍 Code Quality Tools

Pre-commit Hooks

✅ YAML validation
✅ TOML validation
✅ Markdown formatting
✅ Trailing whitespace
✅ End-of-file fixes
✅ GitHub workflow validation

Ruff

Fast Python linter
Replaces flake8, isort, pydocstyle
Auto-fixing capabilities
Extensive rule selection

🧪 Testing Philosophy

What Gets Tested

📝 README code blocks
🔧 Shell scripts (bump, release)
🎯 Makefile targets
📁 Repository structure
📊 Marimo notebooks

Test Command

make test

Runs pytest with coverage reporting and HTML output.

🌐 CI/CD Workflows

10 Automated Workflows

CI — Test matrix across Python versions
PRE-COMMIT — Validate code quality
DEPTRY — Check dependency usage
BOOK — Build documentation
MARIMO — Validate notebooks
DOCKER — Build and publish images
DEVCONTAINER — Validate dev environment
RELEASE — Automated releases
SYNC — Template synchronization
RHIZA — Self-injection test

📦 Package Publishing

PyPI Publication

Automatic if configured as Trusted Publisher:

Register package on PyPI
Add GitHub Actions as trusted publisher
Release workflow publishes automatically

Private Packages

Add to pyproject.toml:

classifiers = [
    "Private :: Do Not Upload",
]

🎯 Real-World Usage

Perfect For:

🆕 New Python projects
🔄 Standardizing existing projects
👥 Team templates
📚 Educational projects
🏢 Corporate standards

Not Ideal For:

❌ Non-Python projects
❌ Projects requiring exotic configurations
❌ One-off scripts

🏗️ Architecture Decisions

Why Makefile?

✅ Universal (no language-specific tools)
✅ Self-documenting
✅ Easy to extend
✅ Works everywhere

Why UV?

⚡ 10-100x faster than pip
📦 Handles entire Python ecosystem
🔒 Lock files for reproducibility
🎯 Single tool for everything

🤝 Contributing

How to Contribute

🍴 Fork the repository
🌿 Create feature branch
✍️ Make your changes
✅ Run make test and make fmt
📤 Submit pull request

What to Contribute

🆕 New templates
🐛 Bug fixes
📚 Documentation improvements
💡 Feature suggestions

📈 Project Stats

🐍 Python Versions: 3.11, 3.12, 3.13, 3.14
📄 License: MIT
🏷️ Current Version: 0.3.0
🔧 Templates: 20+ configuration files
🤖 Workflows: 10 GitHub Actions
⭐ Badge:

🔗 Useful Links

📖 Repository: github.com/jebel-quant/rhiza
📚 Issues: github.com/jebel-quant/rhiza/issues
🚀 Codespaces: Open in GitHub Codespaces
📝 Documentation: Auto-generated with make docs

🙏 Acknowledgments

Built With

GitHub Actions — CI/CD automation
UV — Fast Python package management
Ruff — Fast Python linting
Pytest — Testing framework
Marimo — Interactive notebooks
Marp — This presentation!
pdoc — API documentation
minibook — Companion book

💡 Getting Started Today

Three Simple Steps

Try it: uvx rhiza . in your project
Review: Check the generated .github/template.yml
Sync: Run ./.rhiza/scripts/sync.sh

Or Explore First

# Open in Codespaces
# → Click "Create codespace on main"

# Or clone locally
git clone https://github.com/jebel-quant/rhiza.git
cd rhiza
make install
make test

🎉 Thank You!

Questions?

Rhiza — Your foundation for modern Python projects

From the Greek ῥίζα (root) — because every great project needs strong roots

📋 Quick Reference Card

# Setup
uvx rhiza .                    # Auto-inject Rhiza

# Development
make install                   # Install dependencies
make test                      # Run tests
make fmt                       # Format & lint

# Documentation
make docs                      # API documentation
make book                      # Companion book
make presentation              # Generate slides

# Release
make bump                      # Bump version
make release                   # Create release

# Notebooks
make marimo                    # Interactive notebooks

Ready to Root Your Project?

Get Started: github.com/jebel-quant/rhiza