Skip to content

QUICKSTART.md

Latest commit

 

History

History
237 lines (188 loc) · 6.06 KB

QUICKSTART.md

File metadata and controls

237 lines (188 loc) · 6.06 KB
Raw

Quick Start: GitHub Pages Site for Hub

What Just Happened?

You now have a fully automated GitHub Pages website that:

✅ Auto-generates when you push to main or open PRs
✅ Displays all components with search capability
✅ Requires no maintenance - just add components and they appear
✅ Works offline - search is client-side JavaScript

Files Created

Build System

  • scripts/generate_site.py - Scans hub, generates HTML site
  • .github/workflows/build-docs.yml - GitHub Actions automation

Configuration

  • _config.yml - GitHub Pages settings
  • docs/.nojekyll - Tells GitHub Pages to use static content

Generated (in docs/)

  • index.html - Main hub page with 16 components
  • style.css - All styling
  • search.js - Real-time search engine
  • data.json - Component metadata for search
  • Individual component pages (one per component)

Documentation

  • HUB_GITHUB_PAGES.md - Complete technical guide
  • docs/DEPLOYMENT.md - Deployment details

Next Steps

1. Push to GitHub

cd cellmap_flow_hub
git add -A
git commit -m "Add GitHub Pages automated site generation"
git push origin main

2. Enable GitHub Pages

In GitHub:

  1. Go to repo Settings → Pages
  2. Set source to gh-pages branch
  3. Leave folder as / (root)
  4. Wait for GitHub Actions to complete

3. View Your Site

How It Works

Workflow

You push/PR to main
        ↓
GitHub Actions triggers
        ↓
Python runs: python scripts/generate_site.py . docs
        ↓
Scans normalizers/, postprocessors/, models/, pipelines/
        ↓
Reads config.yaml & README.md from each component
        ↓
Generates HTML site + search index
        ↓
Deploys to gh-pages branch (or uploads artifact for PR)
        ↓
Live at https://cellmap.github.io/cellmap_flow_hub/

Features

🔍 Full-Text Search

  • Search component name, description, author, tags
  • Real-time results as you type
  • Works entirely in browser (no server needed)

📊 Component Discovery

  • Browse by type: Normalizers, Postprocessors, Models, Pipelines
  • See 16 total components at a glance
  • Statistics dashboard

📄 Individual Component Pages

  • Full metadata (version, author, dependencies)
  • Complete documentation from README
  • Installation instructions
  • Use cases and examples

📱 Responsive Design

  • Works on desktop, tablet, mobile
  • Modern styling with no framework dependencies
  • Lightweight and fast

Adding New Components

Before:

normalizers/
├── existing_component/

After:

normalizers/
├── existing_component/
├── my_new_component/
    ├── config.yaml
    ├── README.md
    ├── requirements.txt
    └── normalizer.py

Result:

  • Next PR/push automatically regenerates site
  • Your component appears in grid AND search
  • Individual detail page created
  • Statistics updated

No HTML editing needed!

Testing Locally

# Generate site
python scripts/generate_site.py . docs

# View in browser (choose one)
open docs/index.html                    # macOS
xdg-open docs/index.html                # Linux
start docs/index.html                   # Windows

Then test:

  • Browse components
  • Try searching ("dilate", "normalizer", "CellMapFlow", etc.)
  • Click component cards to see detail pages

Customization (Optional)

Change Site Title/Description

Edit generate_site.py in generate_index_html():

<h1>Your Title Here</h1>
<p>Your description here</p>

Change Colors

Edit generate_css() in :root section:

--primary: #0066cc;      /* Blue */
--secondary: #00aa44;    /* Green */

Modify Component Card Layout

Edit components-grid in CSS section:

grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));

Troubleshooting

Site not updating?

  1. Check GitHub Actions tab for errors
  2. Verify .github/workflows/build-docs.yml exists
  3. Make sure you have at least one valid component

Search not working?

  1. Open browser DevTools (F12)
  2. Check Console for JavaScript errors
  3. Verify data.json exists and is valid JSON

Components not showing?

  1. Verify config.yaml exists in component folder
  2. Ensure YAML is valid (no tabs, proper indentation)
  3. Run locally: python scripts/generate_site.py . docs

File Structure After Setup

cellmap_flow_hub/
├── .github/
│   └── workflows/
│       └── build-docs.yml          ← GitHub Actions
├── scripts/
│   └── generate_site.py            ← Build script
├── docs/                            ← Generated site
│   ├── index.html
│   ├── style.css
│   ├── search.js
│   ├── data.json
│   ├── .nojekyll
│   └── *.html                       ← Component pages
├── normalizers/
├── postprocessors/
├── models/
├── pipelines/
├── _config.yml                      ← GitHub Pages config
└── HUB_GITHUB_PAGES.md              ← Full documentation

Key Benefits

Feature Benefit
Auto-generation Push component, site updates automatically
No registry file Folder structure is the manifest
Client-side search Fast, works offline, no backend needed
Static HTML Works on any platform, ultra-fast
PR preview See changes before merging
No maintenance Just add components, everything else automatic

What's Next?

  1. ✅ Push to main
  2. ✅ Wait for GitHub Actions (check Actions tab)
  3. ✅ Enable GitHub Pages in settings
  4. ✅ Share the link: https://cellmap.github.io/cellmap_flow_hub/
  5. ✅ Invite contributors to add components

Summary

You now have:

  • 16 components discoverable via web interface
  • Real-time search functionality
  • Automated deployment on every push/PR
  • No server required (static HTML site)
  • Scalable architecture for unlimited components

The hub is ready to share with the community! 🚀