🌱 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 - Docs site with MkDocs + zensical - API docs with mkdocstrings - 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
Security scanning (CodeQL, Scorecard)

🎯 Quick Start¶

1. Install the plugin (once)¶

/plugin marketplace add Jebel-Quant/rhiza-claude
/plugin install rhiza@rhiza-claude

2. Adopt, in two pull requests¶

/rhiza:init      # writes .rhiza/template.yml — the pointer. Merge it.
/rhiza:update    # the first sync: the workflows, the Makefile, the rest

/rhiza:init syncs nothing, so its PR looks almost empty — that is correct.

🔄 Template Synchronization¶

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

Configuration: `.rhiza/template.yml`¶

repository: "Jebel-Quant/rhiza"
ref: "v1.5.1"

profiles:
  - github-project

exclude: |
  docs/development/DOCKER.md

A profile expands to its bundles; exclude opts out of individual files.

🔄 Staying Current¶

Syncing is a local command, not a scheduled job — nothing needs a write-scoped token on a timer:

🤖 Renovate opens a PR when the template's ref has a newer release
🔄 /rhiza:update applies it: fetch the bundles, three-way merge, open the PR
🔍 Only template-owned paths are staged — .rhiza/template.lock is the list
🎯 exclude patterns and local edits both survive
📋 /rhiza:status --check reports drift without changing anything

🛠️ Makefile: Your Command Center¶

make install      # Setup project with uv
make test         # Run pytest test suite
make fmt          # Run pre-commit hooks
make book         # Build the companion book
make book         # Build companion book
make presentation # Generate slides from PRESENTATION.md
make marimo       # Launch Marimo notebook server

Note: Releasing is driven by the rhiza-claude /release command, which bumps the version, regenerates the changelog, and creates the tag.

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 docs/notebooks/ with inline dependency management.

🚀 Release Workflow¶

Release (via rhiza-claude `/release`)¶

/release
# → Derives the next version
# → Bumps pyproject.toml
# → Regenerates CHANGELOG.md
# → Creates the git tag locally

Pushing the tag triggers the release workflow. Releasing is not a make target.

Check Status¶

make workflow-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¶

Your own targets, in `local.mk`¶

The Makefile is template-owned and -includes local.mk, which no sync touches. An explicit rule beats its %: catch-all, so shadowing extends a task:

# local.mk — committed
install: $(UVX)
    @sudo apt-get update && sudo apt-get install -y graphviz
    @$(UVX) $(RHIZA_TASK) install

train-model: ## Train the ML model
    @uv run python scripts/train.py

Settings go in pyproject.toml's [tool.rhiza-task] table.

🎨 Documentation Customization¶

The docs site (MkDocs + zensical)¶

Override anything from the base config in your own mkdocs.yml:

INHERIT: docs/mkdocs-base.yml

theme:
  logo: assets/my-logo.png

API pages come from mkdocstrings; extra packages go in the mkdocs-extra-packages setting.

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 book

🙏 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!
MkDocs + zensical — The docs site
mkdocstrings — API documentation

💡 Getting Started Today¶

Three Simple Steps¶

Install: /plugin install rhiza@rhiza-claude in Claude Code
Point: /rhiza:init writes .rhiza/template.yml — review and merge
Sync: /rhiza:update brings the template content in

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 (in Claude Code)
# /rhiza:init                  # become rhiza-managed
# /rhiza:update                # sync the template content

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

# Documentation
make book                      # Companion book
make book                      # Companion book
make presentation              # Generate slides

# Release (driven by the rhiza-claude /release command)
make workflow-status          # Show recent runs for the release workflow

# Notebooks
make marimo                    # Interactive notebooks

Ready to Root Your Project?¶

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