Makefile

# Makefile for Technical Documentation Build System
# Builds diagrams, colors, PDF, and HTML with dark mode support
# Supports multiple projects

.PHONY: all clean colors diagrams pdf html help check test example technical-documentation rebuild install-hook build-project build-summary check-outputs clean-outputs clean-generated server-start server-stop server-status version bump-patch bump-minor bump-major

# Default project (matches the actual source directory)
PROJECT ?= docs

# Theme toggle configuration
# Set to "yes" to include theme toggle button, "no" to use auto (system settings only)
THEME_TOGGLE ?= yes

# Project configurations
TECH_DOC_SRC = docs/main.typ
TECH_DOC_OUT = build/technical-documentation
EXAMPLE_SRC = example/docs/main.typ
EXAMPLE_OUT = example/build/technical-documentation

# Default target - builds the technical-documentation project
all: technical-documentation

# Internal: Build a project (called with SRC, OUT, and PROJECT parameters)
build-project:
	@$(MAKE) colors
	@$(MAKE) diagrams PROJECT=$(PROJECT)
	@$(MAKE) pdf-only SRC=$(SRC) OUT=$(OUT)
	@$(MAKE) html-only SRC=$(SRC) OUT=$(OUT)

# Internal: Show build completion summary
build-summary:
	@echo ""
	@echo "=================================================="
	@echo "✅ Build Complete!"
	@echo "=================================================="
	@echo "📄 PDF:  $(OUT).pdf"
	@echo "🌐 HTML: http://localhost:8000/$(OUT).html"
	@echo ""
	@echo "💡 Click the HTML link above to open in browser"

# Build technical-documentation project (the default for real work)
technical-documentation:
	@echo "=================================================="
	@echo "🚀 Building Technical Documentation Project"
	@echo "=================================================="
	@$(MAKE) build-project SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT) PROJECT=docs
	@$(MAKE) server-start
	@$(MAKE) build-summary OUT=$(TECH_DOC_OUT)
	@echo "🌓 Toggle dark mode with the button in top-right"

# Build example project (uses same build process as technical-documentation)
example:
	@echo "=================================================="
	@echo "🎨 Building Example Project"
	@echo "=================================================="
	@$(MAKE) colors
	@$(MAKE) diagrams PROJECT=example
	@$(MAKE) python-diagrams
	@$(MAKE) python-api
	@$(MAKE) python-tests
	@$(MAKE) pdf-only SRC=$(EXAMPLE_SRC) OUT=$(EXAMPLE_OUT)
	@$(MAKE) html-only SRC=$(EXAMPLE_SRC) OUT=$(EXAMPLE_OUT)
	@$(MAKE) server-start
	@$(MAKE) build-summary OUT=$(EXAMPLE_OUT)
	@echo "🌓 Toggle dark mode with the button in top-right"

# Generate color files (CSS and Typst) from colors.json
colors:
	@echo "🎨 Generating color files..."
	@python3 scripts/build-colors.py

# Build python-project API documentation
python-api:
	@echo "📚 Generating Python API documentation..."
	@cd example/python-project && python3 -m src.doc_generator.extract_api

# Build python-project test reports
python-tests:
	@echo "🧪 Generating Python test reports..."
	@cd example/python-project && python3 -m src.doc_generator.test_report

# Build python-project diagrams (including v-model and build-pipeline)
# Note: These diagrams are in example/docs/diagrams but need theme-aware compilation
python-diagrams:
	@echo "📊 Compiling additional diagrams..."
	@mkdir -p example/build/diagrams
	@typst compile --root . --input theme=light --format svg example/docs/diagrams/v-model.typ example/build/diagrams/v-model-light.svg
	@typst compile --root . --input theme=dark --format svg example/docs/diagrams/v-model.typ example/build/diagrams/v-model-dark.svg
	@cp example/build/diagrams/v-model-light.svg example/build/diagrams/v-model.svg
	@typst compile --root . --input theme=light --format svg example/docs/diagrams/build-pipeline.typ example/build/diagrams/build-pipeline-light.svg
	@typst compile --root . --input theme=dark --format svg example/docs/diagrams/build-pipeline.typ example/build/diagrams/build-pipeline-dark.svg
	@cp example/build/diagrams/build-pipeline-light.svg example/build/diagrams/build-pipeline.svg
	@echo "✓ Additional diagrams created"

# Compile diagrams to SVG (with project parameter)
diagrams: colors
	@echo "📊 Compiling diagrams for $(PROJECT)..."
	@python3 scripts/build-diagrams.py $(PROJECT)

# Internal target: Compile PDF (called with SRC and OUT parameters)
pdf-only:
	@echo "📄 Compiling PDF: $(OUT).pdf..."
	@mkdir -p $$(dirname $(OUT).pdf)
	@typst compile --root . $(SRC) $(OUT).pdf
	@echo "✓ PDF created: $(OUT).pdf"

# Internal target: Compile HTML (called with SRC and OUT parameters)
html-only:
	@echo "🌐 Compiling HTML with Bootstrap: $(OUT).html..."
	@mkdir -p $$(dirname $(OUT).html)
ifeq ($(THEME_TOGGLE),yes)
	@python3 scripts/build-html-bootstrap.py $(SRC) $(OUT).html
else
	@python3 scripts/build-html-bootstrap.py $(SRC) $(OUT).html --no-theme-toggle
endif
	@echo "✓ Bootstrap HTML created: $(OUT).html"

# User-friendly targets for building just PDF or HTML
pdf:
	@$(MAKE) colors
	@$(MAKE) diagrams PROJECT=$(PROJECT)
	@$(MAKE) pdf-only SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT)

html:
	@$(MAKE) colors
	@$(MAKE) diagrams PROJECT=$(PROJECT)
	@$(MAKE) html-only SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT)

# Check for errors without building
check:
	@echo "🔍 Checking configuration..."
	@python3 -c "import json; json.load(open('lib/colors.json')); print('✓ lib/colors.json is valid')"
	@python3 -c "from pathlib import Path; assert Path('lib/technical-documentation-package.typ').exists(); print('✓ Package exists')"
	@python3 -c "from pathlib import Path; assert Path('docs/main.typ').exists(); print('✓ Main document exists')"
	@echo "✅ All checks passed"

# Internal: Check that build outputs exist
check-outputs:
	@test -f build/technical-documentation.pdf && echo "✓ Technical doc PDF exists" || echo "❌ Technical doc PDF missing"
	@test -f build/technical-documentation.html && echo "✓ Technical doc HTML exists" || echo "❌ Technical doc HTML missing"
	@test -f example/build/technical-documentation.pdf && echo "✓ Example PDF exists" || echo "❌ Example PDF missing"
	@test -f example/build/technical-documentation.html && echo "✓ Example HTML exists" || echo "❌ Example HTML missing"
	@test -f lib/generated/colors.css && echo "✓ Colors generated" || echo "❌ Colors missing"

# Quick test - compile everything and check outputs exist
test: technical-documentation example
	@echo "🧪 Testing build outputs..."
	@$(MAKE) check-outputs
	@echo "✅ All tests passed"

# Internal: Remove PDF and HTML outputs
clean-outputs:
	@rm -rf build/
	@rm -rf example/build/
	@rm -rf example/python-project/build/
	@rm -f *_temp*.html

# Internal: Remove generated files
clean-generated:
	@rm -f colors.css
	@rm -f styles-bootstrap.css
	@rm -f lib/generated/colors.css
	@rm -f lib/generated/colors.typ

# Clean build artifacts
clean:
	@echo "🧹 Cleaning build artifacts..."
	@$(MAKE) server-stop 2>/dev/null || true
	@$(MAKE) clean-outputs
	@$(MAKE) clean-generated
	@rm -f .server.pid
	@echo "✓ Clean complete"

# Clean and rebuild everything
rebuild: clean all

# Show help
help:
	@echo "Technical Documentation Build System"
	@echo "===================================="
	@echo ""
	@echo "Main targets:"
	@echo "  make                    - Build technical-documentation (default)"
	@echo "  make example            - Build the example project"
	@echo "  make test               - Build and validate all projects"
	@echo ""
	@echo "Component targets:"
	@echo "  make colors             - Generate color files from colors.json"
	@echo "  make diagrams PROJECT=xxx - Compile diagrams for specific project"
	@echo "  make pdf                - Compile PDF for default project"
	@echo "  make html               - Compile HTML (Bootstrap styling)"
	@echo ""
	@echo "Configuration:"
	@echo "  THEME_TOGGLE=yes|no     - Include theme toggle button (default: yes)"
	@echo "                            Set to 'no' to use auto (system settings only)"
	@echo ""
	@echo "Utility targets:"
	@echo "  make check              - Validate configuration files"
	@echo "  make test               - Build and test all outputs"
	@echo "  make clean              - Remove all build artifacts"
	@echo "  make rebuild            - Clean and rebuild everything"
	@echo "  make help               - Show this help message"
	@echo ""
	@echo "Server targets:"
	@echo "  make server-start       - Start dev server (live-server or Python fallback) on port 8000"
	@echo "  make server-stop        - Stop the HTTP server"
	@echo "  make server-status      - Check server status"
	@echo ""
	@echo "Version management:"
	@echo "  make version            - Show current version from pyproject.toml"
	@echo "  make bump-patch         - Bump patch version (0.3.2 → 0.3.3)"
	@echo "  make bump-minor         - Bump minor version (0.3.2 → 0.4.0)"
	@echo "  make bump-major         - Bump major version (0.3.2 → 1.0.0)"
	@echo ""
	@echo "Pre-commit hook:"
	@echo "  make install-hook       - Install git pre-commit hook"
	@echo ""
	@echo "Examples:"
	@echo "  make                           # Build technical-documentation (starts server)"
	@echo "  make example                   # Build example project (starts server)"
	@echo "  make server-stop               # Stop the HTTP server"
	@echo "  make THEME_TOGGLE=no           # Build without theme toggle (auto only)"
	@echo "  make diagrams PROJECT=example  # Just compile example diagrams"
	@echo "  make rebuild                   # Clean and rebuild"

# Install pre-commit hook
install-hook:
	@echo "📝 Installing pre-commit hook..."
	@mkdir -p .git/hooks
	@cp scripts/build-hooks/pre-commit .git/hooks/pre-commit
	@chmod +x .git/hooks/pre-commit
	@echo "✓ Pre-commit hook installed"
	@echo ""
	@echo "The hook will:"
	@echo "  1. Check if colors.json was modified"
	@echo "  2. Check if diagram .typ files were modified"
	@echo "  3. Rebuild affected components"
	@echo "  4. Stage updated files for commit"

# HTTP Server Management
server-start:
	@if [ -f .server.pid ] && kill -0 $$(cat .server.pid) 2>/dev/null; then \
		echo "✅ Server already running (PID: $$(cat .server.pid))"; \
	else \
		rm -f .server.pid; \
		if command -v live-server >/dev/null 2>&1; then \
			echo "🚀 Starting live-server..."; \
			live-server --port=8000 --no-browser --quiet --wait=100 > /dev/null 2>&1 & echo $$! > .server.pid; \
		else \
			echo "⚠️  live-server not found, falling back to Python server"; \
			python3 scripts/dev-server.py -p 8000 > /dev/null 2>&1 & echo $$! > .server.pid; \
		fi; \
		sleep 1; \
		if [ -f .server.pid ] && kill -0 $$(cat .server.pid) 2>/dev/null; then \
			echo "🌐 Server started (PID: $$(cat .server.pid))"; \
			echo "📖 http://localhost:8000/build/technical-documentation.html"; \
		else \
			echo "❌ Failed to start server (port may be in use)"; \
			rm -f .server.pid; \
			exit 1; \
		fi; \
	fi

server-stop:
	@if [ -f .server.pid ]; then \
		if kill -0 $$(cat .server.pid) 2>/dev/null; then \
			kill $$(cat .server.pid) 2>/dev/null && echo "🛑 Server stopped (PID: $$(cat .server.pid))"; \
		else \
			echo "ℹ️  Server not running (stale PID file)"; \
		fi; \
		rm -f .server.pid; \
	else \
		echo "ℹ️  No PID file found (.server.pid)"; \
		echo "   If server is still running, kill it manually"; \
	fi

server-status:
	@if [ -f .server.pid ]; then \
		if kill -0 $$(cat .server.pid) 2>/dev/null; then \
			echo "✅ Server is running (PID: $$(cat .server.pid))"; \
			echo "📖 http://localhost:8000/"; \
		else \
			echo "❌ Server not running (stale PID file found)"; \
			rm -f .server.pid; \
		fi; \
	else \
		echo "ℹ️  Server not running (no PID file)"; \
		echo "   Start with: make server-start"; \
	fi

# ==============================================================================
# Version Management
# ==============================================================================

# Show current version from pyproject.toml
version:
	@echo "Current version: $$(python3 scripts/get_version.py)"

# Bump patch version (0.3.2 → 0.3.3)
bump-patch:
	@echo "🔄 Bumping patch version..."
	@python3 scripts/bump_version.py patch
	@echo ""
	@echo "📝 Next: Review and update CHANGELOG.md with actual changes"
	@echo "💾 Then: git add pyproject.toml CHANGELOG.md && git commit -m 'chore(release): bump version'"

# Bump minor version (0.3.2 → 0.4.0)
bump-minor:
	@echo "🔄 Bumping minor version..."
	@python3 scripts/bump_version.py minor
	@echo ""
	@echo "📝 Next: Review and update CHANGELOG.md with actual changes"
	@echo "💾 Then: git add pyproject.toml CHANGELOG.md && git commit -m 'chore(release): bump version'"

# Bump major version (0.3.2 → 1.0.0)
bump-major:
	@echo "🔄 Bumping major version..."
	@python3 scripts/bump_version.py major
	@echo ""
	@echo "📝 Next: Review and update CHANGELOG.md with actual changes"
	@echo "💾 Then: git add pyproject.toml CHANGELOG.md && git commit -m 'chore(release): bump version'"