# Makefile for MkDocs MCP Example project
# Provides convenient commands for development workflow
.PHONY: help install dev-install clean format lint typecheck test test-cov docs-serve docs-build mcp-server quality ci-check setup
# Default target
help: ## Show this help message
@echo "MkDocs MCP Example - Development Commands"
@echo "========================================="
@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z_-]+:.*##/ {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
# Installation and Setup
install: ## Install production dependencies
uv sync
dev-install: ## Install development dependencies
uv sync --dev
pre-commit install
setup: dev-install ## Complete development setup
@echo "✅ Development environment setup complete!"
@echo "💡 Try: make docs-serve"
# Code Quality
format: ## Format code with ruff
uv run ruff format .
@echo "✅ Code formatted"
lint: ## Lint code with ruff
uv run ruff check . --fix
@echo "✅ Code linted"
typecheck: ## Run type checking with mypy
uv run mypy .
@echo "✅ Type checking complete"
quality: format lint typecheck ## Run all code quality checks
@echo "✅ All quality checks complete"
# Testing
test: ## Run all tests
uv run pytest
test-cov: ## Run tests with coverage report
uv run pytest --cov --cov-report=html --cov-report=term-missing
@echo "📊 Coverage report generated in htmlcov/"
test-watch: ## Run tests in watch mode
uv run pytest-watch
test-integration: ## Run integration tests only
uv run pytest -m integration
test-unit: ## Run unit tests only (exclude integration)
uv run pytest -m "not integration"
# Documentation
docs-serve: ## Start MkDocs development server
cd mkdocs-site && uv run mkdocs serve -a 0.0.0.0:8000
docs-build: ## Build documentation
cd mkdocs-site && uv run mkdocs build
@echo "📚 Documentation built in mkdocs-site/site/"
docs-clean: ## Clean built documentation
cd mkdocs-site && rm -rf site/
@echo "🧹 Documentation cleaned"
# MCP Server
mcp-server: ## Start MCP server
cd mcp-server && uv run python -m mkdocs_mcp.server
mcp-test: ## Run MCP server tests
cd mcp-server && uv run pytest
# Development Workflow
dev: ## Start development environment (docs + MCP server)
@echo "🚀 Starting development environment..."
@echo "📚 Documentation: http://localhost:8000"
@echo "🔧 MCP Server: Port 8001"
@echo "⏹️ Press Ctrl+C to stop"
@$(MAKE) -j2 docs-serve mcp-server
clean: ## Clean all build artifacts and caches
rm -rf .pytest_cache/
rm -rf .mypy_cache/
rm -rf .ruff_cache/
rm -rf htmlcov/
rm -rf .coverage
cd mkdocs-site && rm -rf site/
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
find . -name "*.pyc" -delete 2>/dev/null || true
@echo "🧹 Cleaned all build artifacts"
# CI/CD
ci-check: quality test ## Run all CI checks (quality + tests)
@echo "✅ All CI checks passed"
pre-commit: ## Run pre-commit hooks on all files
uv run pre-commit run --all-files
# Docker/Podman
container-build: ## Build development container
podman build -t mkdocs-mcp-dev -f .devcontainer/Dockerfile .
container-run: ## Run development container
podman run -it --rm -v $(PWD):/workspace -p 8000:8000 -p 8001:8001 mkdocs-mcp-dev
# Utilities
check-deps: ## Check for outdated dependencies
uv pip list --outdated
update-deps: ## Update dependencies (be careful!)
uv sync --upgrade
freeze: ## Generate requirements.txt files
cd mkdocs-site && uv pip freeze > requirements.txt
cd mcp-server && uv pip freeze > requirements.txt
@echo "📦 Requirements frozen"
# Project Information
info: ## Show project information
@echo "Project: MkDocs MCP Example"
@echo "Python: $$(python --version)"
@echo "uv: $$(uv --version 2>/dev/null || echo 'not installed')"
@echo "Project root: $(PWD)"
@echo "Workspace members:"
@echo " - mkdocs-site (documentation)"
@echo " - mcp-server (MCP server)"
# Quick commands
serve: docs-serve ## Alias for docs-serve
build: docs-build ## Alias for docs-build
server: mcp-server ## Alias for mcp-server
# Validation targets (useful for CI)
validate-mkdocs: ## Validate MkDocs configuration
cd mkdocs-site && uv run mkdocs build --strict --verbose
validate-config: ## Validate all configuration files
@echo "Validating pyproject.toml files..."
@python -c "import tomllib; [tomllib.load(open(f, 'rb')) for f in ['pyproject.toml', 'mkdocs-site/pyproject.toml', 'mcp-server/pyproject.toml']]"
@echo "Validating JSON files..."
@python -c "import json; [json.load(open(f)) for f in ['.devcontainer/devcontainer.json', '.vscode/settings.json', '.vscode/extensions.json', '.vscode/tasks.json', '.vscode/launch.json']]"
@echo "✅ All configuration files valid"
# Release helpers (future use)
check-release: ci-check validate-mkdocs validate-config ## Full release check
@echo "🎉 Ready for release!"
# Development helpers
reset: clean dev-install ## Reset development environment
@echo "🔄 Development environment reset"
status: ## Show git and project status
@echo "Git status:"
@git status --short 2>/dev/null || echo "Not a git repository"
@echo ""
@echo "Workspace status:"
@ls -la mkdocs-site/ mcp-server/ 2>/dev/null || true
