Create GitHub Pages documentation site (fixes #35)

.github/workflows/deploy-pages.yml

@@ -0,0 +1,54 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: cd docs && npm install
+
+      - name: Build site
+        run: cd docs && npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -9,6 +9,8 @@ It is a way for me to remember and hopefully get others started.
 
 Start your Python journey in Python 3. Onward and upward.
 
+**📚 [View the documentation site →](https://james-see.github.io/python-examples/)**
+
 ## 🚀 Quick Start
 
 This project uses [uv](https://github.com/astral-sh/uv) for modern Python package management.

docs/.gitignore

@@ -0,0 +1,22 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.astro/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*

docs/README.md

@@ -0,0 +1,79 @@
+# Python Examples Documentation Site
+
+This is the source for the GitHub Pages documentation site for python-examples.
+
+## 🚀 Built With
+
+- **Astro** - Fast, content-focused static site generator
+- **Academic Paper Design** - Clean, professional typography inspired by research papers
+- **Interactive Filtering** - Search and filter examples by category
+- **Personality** - Easter eggs and touches that show character
+
+## 🛠️ Development
+
+```bash
+cd docs
+
+# Install dependencies
+npm install
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+## 📁 Structure
+
+```
+docs/
+├── src/
+│   ├── layouts/     # Page layouts
+│   ├── pages/       # Astro pages
+│   ├── styles/      # Global CSS
+│   └── components/  # Reusable components (future)
+├── public/          # Static assets
+└── astro.config.mjs # Astro configuration
+```
+
+## 🎨 Design Philosophy
+
+- **Academic aesthetic** - Serif fonts, paper-like background, numbered sections
+- **Monospace code** - JetBrains Mono for all code examples
+- **Accent color** - Burnt orange (#d35400) for personality
+- **Clean typography** - Crimson Pro for body, Inter for UI elements
+- **Interactive** - Search, filters, and easter eggs for engagement
+
+## 🚀 Deployment
+
+The site automatically deploys to GitHub Pages when changes are pushed to master via GitHub Actions.
+
+## 🎯 Features
+
+- ✅ Responsive design
+- ✅ Search functionality
+- ✅ Category filtering
+- ✅ Print-friendly (for actual paper)
+- ✅ Easter egg (Konami code)
+- ✅ Fast static site generation
+- ✅ Academic paper styling
+
+## 📝 Adding New Examples
+
+Edit `src/pages/index.astro` and add to the `examples` array:
+
+```javascript
+{
+  title: 'your-example.py',
+  description: 'What it does',
+  category: 'Category Name',
+  tags: ['tag1', 'tag2'],
+  difficulty: 'beginner' // or 'intermediate', 'advanced'
+}
+```
+
+The site will automatically update filters and search.

docs/astro.config.mjs

@@ -0,0 +1,10 @@
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://james-see.github.io',
+  base: '/python-examples',
+  outDir: '../dist',
+  build: {
+    assets: '_assets'
+  }
+});

docs/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "python-examples-docs",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "astro": "^4.16.18"
+  }
+}

docs/src/layouts/Layout.astro

@@ -0,0 +1,27 @@
+---
+interface Props {
+	title: string;
+}
+
+const { title } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="description" content="A curated collection of Python examples for modern development" />
+		<meta name="viewport" content="width=device-width" />
+		<link rel="icon" type="image/svg+xml" href="/python-examples/favicon.svg" />
+		<meta name="generator" content={Astro.generator} />
+		<title>{title}</title>
+	</head>
+	<body>
+		<div class="paper-container">
+			<slot />
+		</div>
+		<style is:global>
+			@import "../styles/global.css";
+		</style>
+	</body>
+</html>