Build a Tutorial Site

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: 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#

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:

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#

Contents