diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml new file mode 100644 index 0000000..1d111f1 --- /dev/null +++ b/.github/workflows/deploy-pages.yml @@ -0,0 +1,56 @@ +name: Deploy GitHub Pages + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'badgesort/**' + - 'scripts/build_microsite.py' + - '.github/workflows/deploy-pages.yml' + workflow_dispatch: # Allow manual trigger + +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Build microsite + run: python3 scripts/build_microsite.py + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs + + 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 diff --git a/.gitignore b/.gitignore index e435e41..44dfa9f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ __pycache__ .vscode dist/ +docs/index.html diff --git a/README.md b/README.md index 8afa8f8..eda65de 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ ## 🎨 Interactive Generator -**New!** Try the [interactive web-based generator](./docs/) to visually configure and generate your BadgeSort YAML! No installation required - just select your badges, configure the options, and copy the generated GitHub Actions YAML. +**New!** Try the [interactive web-based generator](https://chipwolf.github.io/BadgeSort/) to visually configure and generate your BadgeSort YAML! No installation required - just select your badges, configure the options, and copy the generated GitHub Actions YAML. The live site is automatically deployed from the latest code and displays the build commit hash. + +For local development of the microsite, see [docs/README.md](./docs/README.md). ## Background: diff --git a/docs/BUILD_SYSTEM.md b/docs/BUILD_SYSTEM.md new file mode 100644 index 0000000..1fcb3b2 --- /dev/null +++ b/docs/BUILD_SYSTEM.md @@ -0,0 +1,243 @@ +# Microsite Build and Deployment System + +## Summary + +This document describes the automated build and deployment system for the BadgeSort microsite. + +## Problem + +Previously, the BadgeSort microsite at `/docs/index.html` contained a complete copy of the application code embedded directly in the HTML file. When the main BadgeSort application was updated, the microsite needed to be manually synchronized, leading to: + +- Code duplication +- Maintenance burden +- Risk of the microsite falling out of sync with the main application + +## Solution + +An automated build and deployment system that: + +1. **Separates template from generated output**: The microsite source is now in `docs/index.template.html` with a placeholder for dynamic content (commit hash) +2. **Automates the build**: A Python script (`scripts/build_microsite.py`) generates the final `docs/index.html` by injecting the current commit hash +3. **Automates deployment**: A GitHub Actions workflow (`.github/workflows/deploy-pages.yml`) builds and deploys the microsite to GitHub Pages automatically +4. **Displays build information**: The deployed site shows the commit hash it was built from + +## Architecture + +### Files + +- **`docs/index.template.html`** (source, tracked in git) + - Contains the complete microsite HTML, CSS, JavaScript, and PyScript code + - Includes placeholder `{{COMMIT_HASH}}` for build information + - This is the file to edit when making changes to the microsite + +- **`docs/index.html`** (generated, NOT tracked in git) + - Generated from the template by `scripts/build_microsite.py` + - Has the commit hash placeholder replaced with the actual git commit hash + - Excluded from version control via `.gitignore` + +- **`scripts/build_microsite.py`** + - Python script that builds the microsite + - Reads `docs/index.template.html` + - Injects the current git commit hash + - Writes to `docs/index.html` + +- **`.github/workflows/deploy-pages.yml`** + - GitHub Actions workflow for automated deployment + - Triggered on push to `main` branch when relevant files change + - Can also be manually triggered via workflow_dispatch + - Builds the microsite and deploys to GitHub Pages + +### Build Process + +``` +┌─────────────────────────┐ +│ docs/index.template.html│ +│ (source with {{...}}) │ +└───────────┬─────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ scripts/build_microsite.py│ +│ - Get git commit hash │ +│ - Replace placeholders │ +└───────────┬─────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ docs/index.html │ +│ (generated output) │ +└─────────────────────────┘ +``` + +### Deployment Process + +``` +┌─────────────────────────┐ +│ Push to main branch │ +│ (docs/**, badgesort/** │ +│ or build scripts) │ +└───────────┬─────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ GitHub Actions │ +│ deploy-pages.yml │ +│ 1. Checkout code │ +│ 2. Setup Python │ +│ 3. Build microsite │ +│ 4. Configure Pages │ +│ 5. Upload artifact │ +│ 6. Deploy to Pages │ +└───────────┬─────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ GitHub Pages │ +│ https://chipwolf. │ +│ github.io/BadgeSort/ │ +└─────────────────────────┘ +``` + +## Usage + +### Making Changes to the Microsite + +1. Edit `docs/index.template.html` +2. Test locally: + ```bash + python3 scripts/build_microsite.py + cd docs && python3 -m http.server 8000 + ``` +3. Commit and push to `main` branch +4. GitHub Actions will automatically build and deploy + +### Local Development + +```bash +# Build the microsite +python3 scripts/build_microsite.py + +# Serve locally +cd docs && python3 -m http.server 8000 +# Visit http://localhost:8000/ +``` + +### Manual Deployment + +If needed, the workflow can be manually triggered: +1. Go to the repository's Actions tab +2. Select "Deploy GitHub Pages" workflow +3. Click "Run workflow" +4. Select the branch (usually `main`) +5. Click "Run workflow" + +## Code Maintenance + +### Microsite vs CLI Code + +The microsite Python code (embedded in `docs/index.template.html`) is a **browser-adapted version** of the BadgeSort CLI logic. Key differences: + +- **Microsite**: Uses PyScript, DOM manipulation, JavaScript interop +- **CLI**: Uses standard Python libraries, file I/O, CLI arguments + +When updating badge generation or sorting algorithms: +1. Update `badgesort/icons.py` for CLI functionality +2. Update the corresponding code in `docs/index.template.html` for the microsite +3. Both implementations should be kept conceptually in sync + +The microsite is not automatically generated from the CLI code because: +- Different execution environments (browser vs Python interpreter) +- Different interfaces (DOM vs command-line) +- Different dependencies (PyScript vs system packages) + +### Keeping Code in Sync + +When making changes to badge generation or sorting algorithms, follow this checklist: + +**For CLI Changes** (`badgesort/icons.py`): +- [ ] Update the CLI function (e.g., `run()`, sorting algorithms, badge URL generation) +- [ ] Test the CLI locally: `python -m badgesort.icons -s github python` +- [ ] Update corresponding logic in `docs/index.template.html` (see checklist below) + +**For Microsite Changes** (`docs/index.template.html`): +- [ ] Locate the equivalent function in the embedded Python code (after line 637) +- [ ] Update the logic to match the CLI changes +- [ ] Account for browser-specific differences (PyScript, no file I/O, DOM updates) +- [ ] Test locally: `python3 scripts/build_microsite.py && cd docs && python3 -m http.server` +- [ ] Verify in browser at http://localhost:8000/ + +**Key Areas to Keep in Sync**: +1. **Badge URL generation**: Search for `icon_url =` in both files +2. **Sorting algorithms**: Functions `Hilbert_to_int`, `lum`, `step`, color sort logic +3. **SVG embedding logic**: `svg_to_base64_data_uri` and related functions +4. **Color calculations**: RGB to HSV, brightness calculations, logo color selection + +**Testing Both**: +- [ ] CLI: Run with various options and verify output +- [ ] Microsite: Test all sorting algorithms, badge styles, and providers +- [ ] Compare badge URLs generated by both (should be identical for same inputs) + +## Benefits + +1. **No manual synchronization**: Deployment is fully automated +2. **Version transparency**: Build commit hash visible on the site +3. **Consistent deployments**: Every push to main triggers rebuild +4. **Easy rollback**: Can redeploy any previous commit +5. **Clear separation**: Template vs generated file +6. **No code in git**: Generated file excluded from version control + +## Configuration + +### GitHub Repository Settings + +For the workflow to work, ensure: + +1. **GitHub Pages is enabled**: + - Go to Settings → Pages + - Source: GitHub Actions (not branch-based deployment) + +2. **Workflow permissions**: + - Go to Settings → Actions → General + - Workflow permissions: "Read and write permissions" + - Allow GitHub Actions to create and approve pull requests: Enabled + +### Workflow Triggers + +The workflow triggers on: +- Push to `main` branch when these paths change: + - `docs/**` + - `badgesort/**` + - `scripts/build_microsite.py` + - `.github/workflows/deploy-pages.yml` +- Manual trigger via `workflow_dispatch` + +## Troubleshooting + +### Build fails with "Could not get git commit hash" + +This shouldn't happen in GitHub Actions (git is always available), but if running locally in a non-git directory, the script will use "unknown" as the commit hash. + +### Page not updating after push + +1. Check the Actions tab for workflow runs +2. Verify the workflow completed successfully +3. GitHub Pages may cache content - wait a few minutes or force refresh (Ctrl+F5) +4. Check that the workflow triggers are configured correctly + +### Local build fails + +Ensure you're running from the repository root: +```bash +python3 scripts/build_microsite.py +``` + +## Future Enhancements + +Possible future improvements: + +1. **Automated sync testing**: Add tests that compare CLI and microsite outputs for identical inputs to catch synchronization drift automatically +2. **Minification**: Add HTML/CSS/JS minification to reduce file size +3. **Asset optimization**: Optimize any images or assets +4. **Build caching**: Cache build artifacts for faster deployments +5. **Preview deployments**: Deploy PR previews for testing changes +6. **Code extraction**: Extract shared algorithm logic into a common module that both CLI and microsite can import (would require PyScript package support) diff --git a/docs/README.md b/docs/README.md index c5c93ac..b3afcd1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,24 +10,58 @@ The interactive generator (`index.html`) provides a user-friendly interface to: - Preview badges in real-time - Generate GitHub Actions YAML configuration -## Usage +## Build Process -### Local Development +The microsite is automatically built and deployed via GitHub Actions whenever changes are pushed to the `main` branch. + +### Building Locally + +To build the microsite locally: -1. Serve the directory with a web server: ```bash -python3 -m http.server 8000 +python3 scripts/build_microsite.py ``` -2. Open http://localhost:8000/ in your browser +This will: +1. Read the template from `docs/index.template.html` +2. Inject the current git commit hash +3. Generate `docs/index.html` + +**Note:** The generated `docs/index.html` file is excluded from version control (`.gitignore`) as it is automatically built during deployment. -### Deployment +### Template -To deploy this microsite: +The `index.template.html` file contains: +- HTML structure and styling +- PyScript configuration +- Python code for the interactive badge generator +- Placeholder `{{COMMIT_HASH}}` for build information -1. Host the directory on any static web hosting service (GitHub Pages, Netlify, Vercel, etc.) +When making changes to the microsite, edit `index.template.html` rather than `index.html`. -The microsite is a single-page application with no backend dependencies. PyScript will automatically download and run the Python code in the browser. +## Deployment + +The microsite is automatically deployed to GitHub Pages via the `.github/workflows/deploy-pages.yml` workflow. + +The workflow is triggered on: +- Push to `main` branch (when files in `docs/`, `badgesort/`, or the build script change) +- Manual workflow dispatch + +## Usage + +### Local Development + +1. Make changes to `docs/index.template.html` +2. Build the site: `python3 scripts/build_microsite.py` +3. Serve the directory with a web server: +```bash +cd docs && python3 -m http.server 8000 +``` +4. Open http://localhost:8000/ in your browser + +### Live Site + +The microsite is deployed at: https://chipwolf.github.io/BadgeSort/ ## Features @@ -40,12 +74,22 @@ The microsite is a single-page application with no backend dependencies. PyScrip - **All Sort Algorithms**: Hilbert, HSV, Step, Luminance, and Random sorting - **Missing Logo Detection**: Automatically detects and embeds missing Shields.io logos - **Dual Provider Support**: Shields.io with automatic SVG embedding and Badgen.net +- **Build Information**: Displays the commit hash of the deployed version ## Technical Details - Uses **PyScript** to run Python code directly in the browser -- Reuses the existing BadgeSort Python logic (no code duplication) - Loads Simple Icons package via PyScript (simpleicons==7.21.0) - Shields.io for badge rendering - Responsive design for mobile and desktop -- No build step or backend required +- No backend required +- Built and deployed automatically via GitHub Actions + +## Maintenance + +When updating BadgeSort algorithms or badge generation logic: +1. Update the Python code in `badgesort/icons.py` for the CLI +2. Update the corresponding code in `docs/index.template.html` for the microsite +3. Both implementations should be kept in sync for consistency + +The microsite uses a browser-adapted version of the BadgeSort logic optimized for PyScript and DOM manipulation. diff --git a/docs/index.html b/docs/index.template.html similarity index 99% rename from docs/index.html rename to docs/index.template.html index da06b2e..8d82468 100644 --- a/docs/index.html +++ b/docs/index.template.html @@ -465,6 +465,7 @@

BadgeSort

Interactive Badge Generator for GitHub Actions

View on GitHub → +

Build: {{COMMIT_HASH}}

diff --git a/scripts/build_microsite.py b/scripts/build_microsite.py new file mode 100755 index 0000000..fece709 --- /dev/null +++ b/scripts/build_microsite.py @@ -0,0 +1,65 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""Build script for the BadgeSort microsite. + +This script generates the microsite HTML by combining: +1. The HTML/CSS/JS template from docs/index.template.html +2. The commit hash for display + +The microsite Python code is kept separate from the CLI to handle browser-specific functionality. +""" + +import sys +import subprocess +from pathlib import Path + + +def build_microsite(repo_root, commit_hash): + """Build the microsite HTML file by injecting the commit hash.""" + repo_path = Path(repo_root) + + # Read the template + template_path = repo_path / 'docs' / 'index.template.html' + with open(template_path, 'r', encoding='utf-8') as f: + template = f.read() + + # Replace commit hash placeholder + html_content = template.replace('{{COMMIT_HASH}}', commit_hash[:8]) + + # Write the output + output_path = repo_path / 'docs' / 'index.html' + with open(output_path, 'w', encoding='utf-8') as f: + f.write(html_content) + + print(f"Microsite built successfully!") + print(f" Template: {template_path}") + print(f" Output: {output_path}") + print(f" Commit: {commit_hash[:8]}") + + +def main(): + """Main entry point for the build script.""" + # Get the repo root (parent of scripts directory) + script_dir = Path(__file__).parent + repo_root = script_dir.parent + + # Get the current commit hash + try: + result = subprocess.run( + ['git', 'rev-parse', 'HEAD'], + cwd=repo_root, + capture_output=True, + text=True, + check=True + ) + commit_hash = result.stdout.strip() + except subprocess.CalledProcessError: + print("Warning: Could not get git commit hash, using 'unknown'") + commit_hash = 'unknown' + + # Build the microsite + build_microsite(repo_root, commit_hash) + + +if __name__ == '__main__': + main()