feat: add documentation

.github/workflows/pages.yml

@@ -2,7 +2,7 @@ name: Deploy atlarge-research.github.io/opendt
 
 on:
   push:
-    branches: ["master", "refactor-services"]
+    branches: ["master", "add-documentation"]
   workflow_dispatch:
 
 concurrency:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: up down clean-volumes restart build logs help run test setup install-dev clean-env experiment experiment-down
+.PHONY: up down clean-volumes help test setup clean-env
 
 # Default target
 .DEFAULT_GOAL := help
@@ -20,210 +20,162 @@ PYTHON := $(VENV)/bin/python
 PYTEST := $(VENV)/bin/pytest
 UV := $(shell command -v uv 2> /dev/null)
 
-## up: Stop containers, delete volumes (clean slate), and start fresh (use build=true to rebuild images)
+# =============================================================================
+# Core Commands
+# =============================================================================
+
+## up: Start OpenDT services (use build=true to rebuild images)
 up: clean-volumes
-	@echo "🚀 Starting OpenDT services with clean slate..."
-	@echo "📋 Using config: $(config)"
+	@echo ""
+	@echo "Starting OpenDT..."
+	@echo "Config: $(config)"
+	@echo ""
 	@if [ ! -f "$(config)" ]; then \
-		echo "❌ Error: Config file not found: $(config)"; \
+		echo "Error: Config file not found: $(config)"; \
 		exit 1; \
 	fi
-	@echo "🔧 Initializing run..."
 	@$(PYTHON) scripts/opendt_cli.py init --config $(config)
 	@RUN_ID=$$(cat .run_id) && \
 	if [ ! -f "data/$$RUN_ID/.env" ]; then \
-		echo "❌ Error: data/$$RUN_ID/.env not found after initialization"; \
+		echo "Error: data/$$RUN_ID/.env not found after initialization"; \
 		exit 1; \
 	fi && \
 	set -a && . ./data/$$RUN_ID/.env && set +a && \
 	if [ "$(build)" = "true" ]; then \
-		echo "🔨 Rebuilding Docker images (no cache)..."; \
+		echo "Rebuilding Docker images..."; \
 		docker compose $$PROFILE_FLAG build --no-cache; \
 	fi && \
+	echo "Starting containers..." && \
 	docker compose $$PROFILE_FLAG up -d
-	@echo "✅ Services started!"
 	@echo ""
-	@echo "Available services:"
-	@echo "  - Dashboard:   http://localhost:8000"
-	@echo "  - API Docs:    http://localhost:8000/docs"
-	@echo "  - Postgres:    localhost:5432"
-	@echo "  - Kafka:       localhost:9092"
+	@echo "Services started:"
+	@echo "  Dashboard   http://localhost:3000"
+	@echo "  API         http://localhost:3001"
+	@echo ""
+	@echo "View logs with: make logs-<service>"
 	@echo ""
-	@echo "View logs: make logs"
-
-## run: Alias for 'up' (accepts config parameter)
-run: up
 
 ## down: Stop all containers
 down:
-	@echo "⏹️  Stopping OpenDT services..."
+	@echo ""
+	@echo "Stopping OpenDT services..."
 	@RUN_ID=$$(cat .run_id 2>/dev/null || true); \
 	if [ -n "$$RUN_ID" ] && [ -f "data/$$RUN_ID/.env" ]; then \
 		set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG down; \
 	else \
 		docker compose down; \
 	fi
-	@echo "✅ Services stopped!"
+	@echo "Done."
+	@echo ""
 
-## clean-volumes: Stop containers and delete persistent volumes (Kafka & Postgres)
+## clean-volumes: Stop containers and delete all persistent volumes
 clean-volumes:
-	@echo "🧹 Stopping containers and cleaning persistent volumes..."
-	@RUN_ID=$$(cat .run_id 2>/dev/null || true); \
-	if [ -n "$$RUN_ID" ] && [ -f "data/$$RUN_ID/.env" ]; then \
-		set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG down -v; \
-	else \
-		docker compose down -v; \
-	fi
-	@echo "🗑️  Removing named volumes..."
-	-docker volume rm opendt-postgres-data 2>/dev/null || true
-	-docker volume rm opendt-kafka-data 2>/dev/null || true
-	@echo "✅ Clean slate ready!"
-
-## restart: Restart all services (without cleaning volumes)
-restart:
-	@echo "♻️  Restarting OpenDT services..."
-	@RUN_ID=$$(cat .run_id 2>/dev/null || true); \
-	if [ -n "$$RUN_ID" ] && [ -f "data/$$RUN_ID/.env" ]; then \
-		set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG restart; \
-	else \
-		echo "⚠️  Run environment not found, restarting without profile"; \
-		docker compose restart; \
-	fi
-	@echo "✅ Services restarted!"
-
-## build: Rebuild all Docker images
-build:
-	@echo "🔨 Building Docker images..."
 	@RUN_ID=$$(cat .run_id 2>/dev/null || true); \
 	if [ -n "$$RUN_ID" ] && [ -f "data/$$RUN_ID/.env" ]; then \
-		set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG build --no-cache; \
+		set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG down -v 2>/dev/null || true; \
 	else \
-		echo "⚠️  Run environment not found, building without profile"; \
-		docker compose build --no-cache; \
+		docker compose down -v 2>/dev/null || true; \
 	fi
-	@echo "✅ Images built!"
+	@docker volume rm opendt-kafka-data 2>/dev/null || true
+	@docker volume rm opendt-grafana-storage 2>/dev/null || true
 
-## rebuild: Clean, rebuild (no cache), and start (alias for make up build=true)
-rebuild:
-	@$(MAKE) up build=true
+# =============================================================================
+# Development Commands
+# =============================================================================
 
-## setup: Create virtual environment and install all dependencies
+## setup: Create virtual environment and install dependencies
 setup:
-	@echo "🔧 Setting up development environment..."
+	@echo ""
+	@echo "Setting up development environment..."
 	@if [ -z "$(UV)" ]; then \
-		echo "❌ uv not found. Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"; \
+		echo "Error: uv not found. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"; \
 		exit 1; \
 	fi
-	@echo "Creating virtual environment with uv..."
-	uv venv
+	@echo "Creating virtual environment..."
+	@uv venv
 	@echo "Installing dependencies..."
-	uv pip install -e libs/common
-	uv pip install -e "libs/common[test]"
-	uv pip install -e ".[dev]"
-	@echo "✅ Development environment ready!"
+	@uv pip install -e libs/common
+	@uv pip install -e "libs/common[test]"
+	@uv pip install -e ".[dev]"
+	@echo ""
+	@echo "Done. Activate with: source .venv/bin/activate"
 	@echo ""
-	@echo "Activate with: source .venv/bin/activate"
-
-## install-dev: Install dependencies in existing venv (for CI or manual setup)
-install-dev:
-	@echo "📦 Installing development dependencies..."
-	@if [ ! -d "$(VENV)" ]; then \
-		echo "❌ Virtual environment not found. Run 'make setup' first."; \
-		exit 1; \
-	fi
-	$(PYTHON) -m pip install -e libs/common
-	$(PYTHON) -m pip install -e "libs/common[test]"
-	$(PYTHON) -m pip install -e ".[dev]"
-	@echo "✅ Dependencies installed!"
 
-## test: Run tests for shared library
+## test: Run tests
 test:
-	@echo "🧪 Running tests..."
+	@echo ""
+	@echo "Running tests..."
 	@if [ ! -d "$(VENV)" ]; then \
-		echo "Virtual environment not found. Running 'make setup'..."; \
+		echo "Virtual environment not found. Running setup..."; \
 		$(MAKE) setup; \
 	fi
 	@if [ ! -f "$(PYTEST)" ]; then \
-		echo "pytest not found. Running 'make install-dev'..."; \
-		$(MAKE) install-dev; \
+		echo "pytest not found. Running setup..."; \
+		$(MAKE) setup; \
 	fi
-	$(PYTEST) libs/common/tests/ -v --tb=short
-	@echo "✅ Tests passed!"
+	@$(PYTEST) libs/common/tests/ -v --tb=short
+	@echo ""
+	@echo "All tests passed."
+	@echo ""
 
 ## clean-env: Remove virtual environment
 clean-env:
-	@echo "🧹 Removing virtual environment..."
-	rm -rf $(VENV)
-	rm -rf .uv
-	@echo "✅ Environment cleaned!"
-
-## logs: Tail logs for all services
-logs:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG logs -f
+	@echo ""
+	@echo "Removing virtual environment..."
+	@rm -rf $(VENV)
+	@rm -rf .uv
+	@echo "Done."
+	@echo ""
 
-## logs-dashboard: Tail logs for dashboard service only
-logs-dashboard:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose logs -f dashboard
+# =============================================================================
+# Logging Commands
+# =============================================================================
 
-## logs-kafka: Tail logs for Kafka service only
-logs-kafka:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose logs -f kafka
+## logs-api: Tail logs for api service
+logs-api:
+	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose logs -f api
 
-## logs-dc-mock: Tail logs for dc-mock service only
+## logs-dc-mock: Tail logs for dc-mock service
 logs-dc-mock:
 	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose logs -f dc-mock
 
-## logs-simulator: Tail logs for simulator service only
+## logs-simulator: Tail logs for simulator service
 logs-simulator:
 	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose logs -f simulator
 
-## logs-calibrator: Tail logs for calibrator service only
+## logs-calibrator: Tail logs for calibrator service
 logs-calibrator:
 	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose --profile calibration logs -f calibrator
 
-## up-with-calibration: Start services including calibrator
-# up-with-calibration: clean-volumes
-# 	@echo "🚀 Starting OpenDT services with calibration enabled..."
-# 	@echo "📋 Using config: $(config)"
-# 	@if [ ! -f "$(config)" ]; then \
-# 		echo "❌ Error: Config file not found: $(config)"; \
-# 		exit 1; \
-# 	fi
-# 	@if [ "$(build)" = "true" ]; then \
-# 		echo "🔨 Rebuilding Docker images (no cache)..."; \
-# 		CONFIG_PATH=$(config) docker compose --profile calibration build --no-cache; \
-# 		echo "✅ Images rebuilt!"; \
-# 	fi
-# 	CONFIG_PATH=$(config) docker compose --profile calibration up -d
-# 	@echo "✅ Services started with calibration!"
-# 	@echo ""
-# 	@echo "Available services:"
-# 	@echo "  - Dashboard:   http://localhost:8000"
-# 	@echo "  - Calibrator:  Automatic power model calibration"
-# 	@echo "  - Postgres:    localhost:5432"
-# 	@echo "  - Kafka:       localhost:9092"
-# 	@echo ""
-# 	@echo "View logs: make logs-calibrator"
-
-## ps: Show running containers
-ps:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose $$PROFILE_FLAG ps
-
-## shell-dashboard: Open a shell in the dashboard container
-shell-dashboard:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose exec dashboard /bin/bash
-
-## shell-postgres: Open psql in the Postgres container
-shell-postgres:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose exec postgres psql -U opendt -d opendt
-
-## kafka-topics: List Kafka topics
-kafka-topics:
-	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose exec kafka kafka-topics --bootstrap-server localhost:9092 --list
-
-## help: Show this help message
+# =============================================================================
+# Shell Commands
+# =============================================================================
+
+## shell-api: Open a shell in the api container
+shell-api:
+	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose exec api /bin/bash
+
+## shell-dc-mock: Open a shell in the dc-mock container
+shell-dc-mock:
+	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose exec dc-mock /bin/bash
+
+## shell-simulator: Open a shell in the simulator container
+shell-simulator:
+	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose exec simulator /bin/bash
+
+## shell-calibrator: Open a shell in the calibrator container
+shell-calibrator:
+	@RUN_ID=$$(cat .run_id) && set -a && . ./data/$$RUN_ID/.env && set +a && docker compose --profile calibration exec calibrator /bin/bash
+
+# =============================================================================
+# Help
+# =============================================================================
+
+## help: Show available commands
 help:
-	@echo "OpenDT Makefile Commands"
-	@echo "========================"
 	@echo ""
-	@sed -n 's/^##//p' ${MAKEFILE_LIST} | column -t -s ':' | sed -e 's/^/ /'
+	@echo "OpenDT Commands"
+	@echo "==============="
+	@echo ""
+	@sed -n 's/^##//p' ${MAKEFILE_LIST} | column -t -s ':' | sed -e 's/^/  /'
+	@echo ""