Makefile Documentation

This document describes the Makefile provided with the Kaira project, a tool for AI research and development. The Makefile defines several targets to help with common development tasks such as cleaning build artifacts, running tests, syncing branches, and formatting code.

Introduction

Kaira uses a Makefile to streamline common development tasks and provide a consistent interface for project maintenance. This simplifies the workflow for both new and experienced contributors.

File Location

The Makefile is located at the root of the repository: Makefile.

Usage

To use the Makefile, run make <target> from the project root directory, where <target> is one of the available targets described below.

For example:

# Display help information
make help

# Run the test suite
make test

Overview

The Makefile contains the following targets:

help: Display target help with short descriptions.
clean: Remove autogenerated files including build artifacts, caches, and temporary files.
clean-logs: Remove log files.
format: Run pre-commit hooks to format code and check for issues.
sync: Update the current branch with changes from the main branch.
test: Run tests excluding slow ones.
test-full: Run all tests.
lint: Run linting checks on the codebase.
coverage: Run tests with coverage analysis.
deploy: Deploy the package to PyPI.
build-docs: Generate HTML documentation.
build-readme: Build README.rst from template.

Targets in Detail

help

The help target scans the Makefile for lines with comments (using the ## marker) and displays all available targets with their descriptions:

help:  ## Show help
    @grep -E '^[.a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

clean

The clean target removes temporary and autogenerated files. This is useful when you want to ensure a clean state for your project.

clean: ## Clean autogenerated files
    rm -rf dist
    find . -type f -name "*.DS_Store" -ls -delete
    find . | grep -E "(__pycache__|\.pyc|\.pyo)" | xargs rm -rf
    find . | grep -E ".pytest_cache" | xargs rm -rf
    find . | grep -E ".ipynb_checkpoints" | xargs rm -rf
    rm -f .coverage

clean-logs

The clean-logs target deletes all files under the logs directory, which is useful when you want to clear out old logs.

clean-logs: ## Clean logs
    rm -rf logs/**

format

The format target runs all pre-commit hooks to automatically format code and check for basic hygiene issues. This ensures code consistency and catches common problems early.

format: ## Run pre-commit hooks
    pre-commit run -a

sync

The sync target pulls the latest changes from the remote main branch and merges them into the current branch, keeping your development branch up to date.

sync: ## Merge changes from main branch to your current branch
    git pull
    git pull origin main

test

The test target uses pytest to run tests that are marked as not slow. This is useful for quick validation during development.

test: ## Run not slow tests
    pytest -k "not slow"

test-full

The test-full target runs all available tests, including the slow ones, for a complete validation of the codebase.

test-full: ## Run all tests
    pytest

lint

The lint target runs linting checks on the codebase to identify potential issues, style violations, and other code quality concerns.

lint: ## Run linting checks
    ./scripts/lint.sh

coverage

The coverage target runs tests with coverage analysis to measure the extent of test coverage across the codebase.

coverage: ## Run tests with coverage analysis
    python ./scripts/run_coverage.py

deploy

The deploy target handles the process of packaging and deploying the Kaira package to PyPI, making it available for installation via pip.

deploy: ## Deploy package to PyPI
    ./scripts/deploy.sh

build-docs

The build-docs target generates HTML documentation from RST files, making the documentation easily browsable.

build-docs: ## Generate HTML documentation
    ./scripts/build_docs.sh

build-readme

The build-readme target builds the README.rst file from a template, ensuring the project’s front-facing documentation stays updated.

build-readme: ## Build README.rst from template
    python ./scripts/build_readme.py

Common Use Cases

Before submitting a pull request:

# Format code and run quick tests
make format && make test

# Checking code quality before committing
make format && make lint

# Comprehensive check before submitting a pull request
make clean && make format && make lint && make test-full && make coverage

# Preparing a new release
make clean && make test-full && make coverage && make build-docs && make build-readme && make deploy

Development Workflow Example

Here’s a typical workflow for Kaira development:

Sync with the main branch:
```
make sync
```
Make your code changes
Format code and run linting checks: