Add GitHub Pages deployment with notebook execution

[Copilot]

Implements automated deployment of course materials to GitHub Pages with executed Jupyter notebook outputs and preserved repository structure.

Changes

GitHub Actions Workflow (.github/workflows/deploy-pages.yml)

• Triggers on push to master
• Executes notebooks, converts to HTML, deploys via actions/deploy-pages@v4

Build Script (scripts/build_site.py)

• Executes notebooks with nbconvert (600s timeout, 120s cleanup buffer)
• Converts markdown to HTML with inline GitHub-style CSS
• Rewrites relative links: .ipynb → .html, .md → .html, README.md → index.html
• Copies static assets (PDFs, images) preserving directory structure
• Continues build on notebook execution failures (network/dependency errors expected)
• Caches Pygments CSS for performance

Dependencies (requirements.txt)

• Core: nbconvert>=7.17.0 (fixes CVE in ≤7.16.6), jupyter, markdown, Pygments
• Runtime: numpy, pandas, scikit-learn, matplotlib, seaborn, gymnasium
• Optional: dtreeviz, kagglehub

Technical Details

Link Rewriting Order:

1. README.md links → index.html (before generic .md conversion)
2. .ipynb files → .html
3. .md files → .html

Path Exclusion:
Checks path components individually (not substring matching) to avoid false positives like my_site_notes.md matching _site.

Error Handling:
Build exits 0 with warnings when notebooks fail (missing deps, network), allowing deployment to proceed with partial content.

Post-Merge Setup

Repository owner: Settings → Pages → Source: "GitHub Actions"

Site: https://avidaldo.github.io/ia25/

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• api.openml.org
  • Triggering command: /usr/bin/python /usr/bin/python -m ipykernel_launcher -f /tmp/tmpv1v665ym.json --HistoryManager.hist_file=:memory: (dns block)
  • Triggering command: /usr/bin/python /usr/bin/python -m ipykernel_launcher -f /tmp/tmpxfwqo9fj.json --HistoryManager.hist_file=:memory: (dns block)
  • Triggering command: /usr/bin/python /usr/bin/python -m ipykernel_launcher -f /tmp/tmpgvqajdkx.json --HistoryManager.hist_file=:memory: --global p/bin/bash credential.usernfind (dns block)
• ndownloader.figshare.com
  • Triggering command: /usr/bin/python /usr/bin/python -m ipykernel_launcher -f /tmp/tmp9qmqw0lw.json --HistoryManager.hist_file=:memory: (dns block)
  • Triggering command: /usr/bin/python /usr/bin/python -m ipykernel_launcher -f /tmp/tmpr1adim0s.json --HistoryManager.hist_file=:memory: (dns block)
  • Triggering command: /usr/bin/python /usr/bin/python -m ipykernel_launcher -f /tmp/tmp5d0dfxjn.json --HistoryManager.hist_file=:memory: --global /home/REDACTED/.ca/home/REDACTED/work/ia25/ia25/qlearning/qlearning.ipynb ry: (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Add GitHub Pages Deployment for Course Materials

Objective

Set up automatic deployment to GitHub Pages that mirrors the repository structure while showing executed notebook outputs. Students should be able to read materials online in a similar way to browsing the repo locally.

Requirements

1. GitHub Actions Workflow

Create .github/workflows/deploy-pages.yml that:

• Triggers on push to master branch
• Executes all Jupyter notebooks (with outputs)
• Converts notebooks and markdown files to HTML
• Preserves the exact directory structure
• Deploys to GitHub Pages

2. Build Script

Create scripts/build_site.py that:

• Finds all .ipynb files and executes them with nbconvert
• Converts all .md files to HTML using markdown library
• Preserves directory structure in _site/ output folder
• Converts README.md to index.html (main entry point)
• Copies static files (PDFs, images, etc.)
• Maintains relative links between files
• Applies simple, GitHub-like styling to all HTML pages

3. Dependencies File

Create requirements.txt with necessary packages:

• jupyter
• nbconvert
• numpy
• pandas
• scikit-learn
• matplotlib
• seaborn
• markdown
• Pygments (for code highlighting)

4. Styling

Apply minimal, GitHub-like CSS that:

• Uses GitHub's font stack and colors
• Makes content readable and familiar
• Properly styles code blocks, tables, and lists
• Works for both markdown and notebook HTML
• Is responsive for mobile viewing

Expected Structure

avidaldo/ia25/
├── .github/
│   ��── workflows/
│       └── deploy-pages.yml          # GitHub Actions workflow
├── scripts/
│   └── build_site.py                 # Build script
├── requirements.txt                   # Python dependencies
└── [existing content unchanged]

Expected Behavior

1. Push to master branch triggers workflow
2. Workflow installs dependencies from requirements.txt
3. Build script executes all notebooks and converts all content
4. Site is deployed to https://avidaldo.github.io/ia25/
5. README content appears at the root URL
6. All links work correctly (notebooks, markdown files, external repos)
7. Notebooks display with executed outputs and visualizations

Important Notes

• Don't modify existing content files (notebooks, markdown, etc.)
• Preserve all relative links from README and other files
• Handle execution errors gracefully - if a notebook fails, log the error but continue building other files
• Keep the GitHub aesthetic - students should feel it's familiar
• Exclude .ipynb_checkpoints and other temp files from the build
• Use execution timeout of 600 seconds per notebook to prevent hanging

Testing Checklist

After deployment, verify:

• README renders as homepage
• Notebooks show executed outputs
• Markdown files render correctly
• Links between files work
• Images and plots display
• Code syntax highlighting works
• Navigation is intuitive
• PDF link works (data-science-cheatsheet.pdf)

GitHub Pages Configuration

After merging, the repository owner needs to:

1. Go to Settings → Pages
2. Set Source to "GitHub Actions"
3. Wait for first deployment to complete

The site will then be available at https://avidaldo.github.io/ia25/

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.