# GitHub Actions Setup Guide

This guide explains how to configure GitHub Actions for automatic PyPI publishing and documentation deployment.

## Prerequisites

1. A GitHub repository for CaDaR
2. A PyPI account with API token
3. Admin access to your GitHub repository

## Step 1: Set Up PyPI API Token

### Create PyPI API Token

1. Go to [PyPI Account Settings](https://pypi.org/manage/account/)
2. Scroll to "API tokens" section
3. Click "Add API token"
4. Name it: `cadar-github-actions`
5. Scope: Select "Entire account" or specific to "cadar" project
6. Click "Add token"
7. **Copy the token** (you won't see it again!)

### Add Token to GitHub Secrets

1. Go to your GitHub repository
2. Navigate to **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Name: `PYPI_API_TOKEN`
5. Value: Paste your PyPI API token (starts with `pypi-`)
6. Click **Add secret**

## Step 2: Enable GitHub Pages

1. Go to your GitHub repository
2. Navigate to **Settings** → **Pages**
3. Under "Build and deployment":
   - Source: Select **GitHub Actions**
4. Click **Save**

## Step 3: Configure Repository Settings

### Enable Workflow Permissions

1. Go to **Settings** → **Actions** → **General**
2. Scroll to "Workflow permissions"
3. Select **Read and write permissions**
4. Check **Allow GitHub Actions to create and approve pull requests**
5. Click **Save**

## Step 4: Push Your Code

```bash
# Commit all changes
git add .
git commit -m "Add GitHub Actions workflows for PyPI and documentation"

# Push to GitHub (you'll need to authenticate)
git push -u origin main
```

## Step 5: Create and Push a Release Tag

### Create a Tag

```bash
# Create an annotated tag (format: v0.1.0)
git tag -a v0.1.0 -m "Release version 0.1.0"

# Push the tag to GitHub
git push origin v0.1.0
```

This will automatically trigger:
1. **PyPI Publishing Workflow**: Builds wheels for all platforms and publishes to PyPI
2. **Documentation Workflow**: Builds and deploys documentation to GitHub Pages

## How It Works

### Tag Format

- Tags must follow the format: `v*.*.*` (e.g., `v0.1.0`, `v1.2.3`)
- The `v` prefix is stripped for PyPI version (v0.1.0 → 0.1.0)

### PyPI Publishing Workflow

When you push a tag like `v0.1.0`:

1. **Version Extraction**: The `v` prefix is removed (v0.1.0 → 0.1.0)
2. **Version Update**: Updates `Cargo.toml` and `pyproject.toml` with the version
3. **Multi-Platform Build**: Builds wheels for:
   - Linux (all Python versions: 3.8, 3.9, 3.10, 3.11, 3.12)
   - macOS (Python 3.10, 3.11, 3.12)
   - Windows (Python 3.10, 3.11, 3.12)
4. **PyPI Publishing**: Publishes all wheels to PyPI
5. **GitHub Release**: Creates a GitHub release with all built wheels

### Documentation Workflow

When you push a tag:

1. **Build Documentation**:
   - Generates Python API docs
   - Builds Rust documentation
   - Creates MkDocs site
2. **Version Management**:
   - Creates a versioned documentation folder (e.g., `versions/0.1.0/`)
   - Updates the versions index
3. **Deploy to GitHub Pages**:
   - Deploys documentation to `https://oit-technologies.github.io/CaDaR/`
   - Latest version is always at the root
   - Versioned docs at `/versions/0.1.0/`

## Workflow Files

### `.github/workflows/publish-pypi.yml`

- **Triggers**: On tag push matching `v*.*.*`
- **Jobs**:
  - `build-and-publish`: Builds wheels for all platforms
  - `publish`: Publishes to PyPI and creates GitHub release
- **Secrets Required**: `PYPI_API_TOKEN`

### `.github/workflows/docs.yml`

- **Triggers**:
  - On tag push matching `v*.*.*`
  - On push to `main` branch (for dev docs)
- **Jobs**:
  - `build-docs`: Builds documentation
  - `deploy-docs`: Deploys to GitHub Pages
- **Permissions Required**: Write access to pages

## Testing the Setup

### Test Documentation Build Locally

```bash
# Install dependencies
pip install mkdocs mkdocs-material mkdocstrings[python]

# Build and serve docs locally
cd docs
mkdocs serve

# Open http://127.0.0.1:8000 in your browser
```

### Test PyPI Build Locally

```bash
# Install maturin
pip install maturin

# Build wheel locally
maturin build --release

# Check the built wheel
ls -lh target/wheels/
```

## Release Process

### Creating a New Release

1. **Update version in files** (optional, GitHub Actions does this automatically):
   ```bash
   # Update version in Cargo.toml
   sed -i 's/version = .*/version = "0.2.0"/' Cargo.toml

   # Update version in pyproject.toml
   sed -i 's/version = .*/version = "0.2.0"/' pyproject.toml
   ```

2. **Update CHANGELOG.md**:
   ```bash
   # Add your changes to CHANGELOG.md
   vim CHANGELOG.md
   ```

3. **Commit changes**:
   ```bash
   git add .
   git commit -m "Prepare for v0.2.0 release"
   git push origin main
   ```

4. **Create and push tag**:
   ```bash
   git tag -a v0.2.0 -m "Release version 0.2.0"
   git push origin v0.2.0
   ```

5. **Monitor GitHub Actions**:
   - Go to **Actions** tab in your repository
   - Watch the workflows execute
   - Check for any errors

6. **Verify deployment**:
   - PyPI: https://pypi.org/project/cadar/
   - Docs: https://oit-technologies.github.io/CaDaR/
   - GitHub Release: https://github.com/Oit-Technologies/CaDaR/releases

## Troubleshooting

### PyPI Publishing Fails

**Error**: `Invalid API token`
- **Solution**: Check that `PYPI_API_TOKEN` secret is correctly set in GitHub

**Error**: `Version already exists`
- **Solution**: You've already published this version. Increment the version number.

### Documentation Build Fails

**Error**: `Permission denied`
- **Solution**: Enable write permissions in Settings → Actions → General

**Error**: `Module not found: cadar`
- **Solution**: Ensure `maturin develop` runs successfully in the workflow

### Wheels Not Building

**Error**: `Rust compiler not found`
- **Solution**: The workflow installs Rust automatically. Check the workflow logs.

**Error**: `Python version not found`
- **Solution**: Verify the Python version is in the build matrix

## Advanced Configuration

### Building for Specific Platforms Only

Edit `.github/workflows/publish-pypi.yml`:

```yaml
strategy:
  matrix:
    os: [ubuntu-latest]  # Only Linux
    python-version: ['3.11', '3.12']  # Only recent versions
```

### Customizing Documentation Theme

Edit `docs/mkdocs.yml`:

```yaml
theme:
  name: material
  palette:
    primary: your-color
```

### Adding More Documentation Pages

1. Create markdown files in `docs/`
2. Update navigation in `docs/mkdocs.yml`:

```yaml
nav:
  - Home: index.md
  - Your New Page: your-page.md
```

## Support

If you encounter issues:

1. Check the [GitHub Actions logs](https://github.com/Oit-Technologies/CaDaR/actions)
2. Review this setup guide
3. Open an issue on GitHub

## Summary

Once configured:

1. **Push a tag** → Automatic PyPI publish + GitHub release
2. **Documentation** → Automatically built and deployed
3. **Versioned docs** → Each release gets its own documentation version

That's it! Your releases are now fully automated. 🎉
