# Build a Tutorial Site

This site is a Jupyter Book deployed to GitHub Pages. The setup below can be reused for another notebook-based tutorial collection.

## Prerequisites

- A GitHub repository (this one: `DaminK/AnnData_Pytorch_Tutorials`)
- Push access to the repository

## Setup Steps

### 1. Enable GitHub Pages

1. Go to your repository on GitHub: https://github.com/DaminK/AnnData_Pytorch_Tutorials
2. Click on **Settings** (top right)
3. In the left sidebar, click on **Pages**
4. Under "Build and deployment":
   - Source: Select **GitHub Actions**
   - This will allow the workflow in `.github/workflows/deploy.yml` to deploy to GitHub Pages

### 2. Workflow Permissions

1. In the same Settings area, go to **Actions** > **General** (in the left sidebar)
2. Scroll down to "Workflow permissions"
3. Select **Read and write permissions**
4. Check **Allow GitHub Actions to create and approve pull requests** (optional but helpful)
5. Click **Save**

### 3. Trigger the Deployment

The workflow will automatically trigger when you push to the `main` branch. You can also:

1. Go to **Actions** tab in your repository
2. Select the "Deploy Jupyter Book" workflow
3. Click **Run workflow** > **Run workflow** to manually trigger it

During the workflow:
- Notebooks are copied into `docs/notebooks/` so they are bundled into the site
- Jupyter Book executes notebooks (with caching) so outputs are published to GitHub Pages

### 4. Wait for Deployment

- The workflow takes a few minutes to complete
- You can monitor progress in the **Actions** tab
- Once complete, your site will be available at: **https://damink.github.io/AnnData_Pytorch_Tutorials/**

## Updating the Tutorials

To update the tutorials:

1. Make changes to the notebooks or documentation files
2. Commit and push to the `main` branch
3. The GitHub Actions workflow will automatically rebuild and deploy the site

## Local Development

To build and preview the site locally:

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install "jupyter-book<1.0"

# Copy notebooks into the docs tree so they are included in the build
rsync -a notebooks/ docs/notebooks/

# Build the book
cd docs
jupyter-book build .

# Open the built HTML in your browser
# The file is at: _build/html/index.html
```

## Troubleshooting

### Build Fails

- Check the Actions tab for error messages
- Ensure all dependencies are listed in `requirements.txt`
- Verify the `_config.yml` and `_toc.yml` files are correctly formatted

### Site Not Updating

- Check that the workflow completed successfully in the Actions tab
- GitHub Pages may take a few minutes to update after deployment
- Clear your browser cache

### Notebooks Not Rendering

- Ensure notebooks are valid JSON (not corrupted)
- Check that notebooks are listed in `_toc.yml`
- Review the build logs in the Actions tab

## Configuration Files

- `_config.yml`: Main configuration for Jupyter Book
- `_toc.yml`: Table of contents structure
- `.github/workflows/deploy.yml`: GitHub Actions deployment workflow

## Additional Resources

- [Jupyter Book Documentation](https://jupyterbook.org/)
- [GitHub Pages Documentation](https://docs.github.com/en/pages)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)