OpenPlains Learning

Development Setup

This project uses uv for Python package management, Jupyter notebooks for interactive development, and Quarto for rendering.

Prerequisites

• uv
• Quarto CLI

Initial Setup

# Clone the repository
git clone 
cd 

# Create virtual environment and install dependencies
uv sync

Register Jupyter Kernel

# Register the Jupyter kernel (makes this environment available in notebooks)
uv run python -m ipykernel install --user --name=

Recommended VS Code Setup

1. Install extensions:

   • Python
   • Jupyter
   • Quarto (optional, for .qmd files)

2. Select the interpreter:

   • Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
   • Run Python: Select Interpreter
   • Choose the .venv folder created by uv (usually ./.venv/bin/python)

3. Select kernel in notebooks:

   • Open any .ipynb file
   • Click the kernel picker in the top-right
   • Select the .venv environment

Tip: VS Code automatically detects the .venv folder created by uv sync. If it doesn't appear, reload the window.

Recommended VS Code Settings

Add to .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "jupyter.notebookFileRoot": "${workspaceFolder}",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

Daily Workflow

Running Jupyter Lab:

uv run jupyter lab

Running a single notebook:

uv run jupyter execute notebook.ipynb

Rendering with Quarto:

# Preview (live reload)
quarto preview notebook.qmd

# Render to output format
quarto render notebook.qmd

# Redner entire project
uv run quarto preview --port 4444

Note: Quarto automatically uses the virtual environment when you run quarto render from within the project directory, or you can specify the kernel in YAML front matter.

Adding Dependencies

# Add a runtime dependency
uv add pandas

# Add a development dependency
uv add --dev pytest

# Sync after pulling changes
uv sync

Notebook Best Practices

1. Select the correct kernel — In Jupyter, select the <project-name> kernel registered during setup

2. Clear outputs before committing — Keeps diffs clean and repo size small:

   uv run jupyter nbconvert --clear-output --inplace *.ipynb

3. Use Quarto's freeze — For reproducible renders without re-execution:

   # In _quarto.yml or notebook front matter
   execute:
       freeze: auto

Project Structure

├── pyproject.toml      # Project metadata and dependencies
├── uv.lock             # Locked dependencies (commit this)
├── _quarto.yml         # Quarto project config (if applicable)
├── notebooks/          # Jupyter notebooks
└── src/                # Python source code

Publishing the Website

The website is pubished to GitHub Pages when you commit to the main branch.