mirror of https://github.com/harvard-edge/cs249r_book.git synced 2026-04-29 17:20:21 -05:00

Files

Vijay Janapa Reddi 853eb03ee8 style: apply consistent whitespace and formatting across codebase

2025-12-13 14:05:34 -05:00

12 KiB

Raw Blame History

Book Binder CLI

The Book Binder is a self-contained, lightning-fast development CLI for the MLSysBook project. It provides streamlined commands for building, previewing, and managing the book in both HTML and PDF formats.

Quick Start

# First time setup
./binder setup

# Welcome and overview
./binder hello

# Build a single chapter (HTML)
./binder build intro

# Build multiple chapters together (HTML)
./binder build intro,ml_systems

# Preview a chapter (builds and opens in browser)
./binder preview intro

# Build the complete book (HTML)
./binder build

# Build the complete book (PDF)
./binder pdf

# Build a single chapter (PDF) - SELECTIVE BUILD
./binder pdf intro
# ↳ Automatically comments out all chapters except index.qmd and introduction.qmd

# Publish the book
./binder publish

# Get help
./binder help

Installation

The binder is a Python script located in the project root. Make sure it's executable:

chmod +x binder

Dependencies: Python 3.6+ (uses only standard library modules)

Command Reference

⚡ Core Commands

Intuitive commands that work on both individual chapters and the entire book.

Command	Description	Example
`build [chapter[,ch2,...]]`	Build book or chapter(s) in HTML	`./binder build intro,ml_systems`
`preview [chapter[,ch2,...]]`	Preview book or chapter(s)	`./binder preview ops`
`pdf [chapter[,ch2,...]]`	Build book or chapter(s) in PDF	`./binder pdf intro`

Smart defaults: No target = entire book, with target = specific chapter(s)

📚 Full Book Examples

Command	Description	Example
`build`	Build complete book (HTML)	`./binder build`
`preview`	Preview complete book	`./binder preview`
`pdf`	Build complete book (PDF)	`./binder pdf`
`publish`	Build and publish book	`./binder publish`

🔧 Management Commands

Command	Description	Example
`setup`	Configure environment	`./binder setup`
`clean`	Clean configs & artifacts	`./binder clean`
`switch <format>`	Switch active config	`./binder switch pdf`
`status`	Show current status	`./binder status`
`list`	List available chapters	`./binder list`
`doctor`	Run comprehensive health check	`./binder doctor`
`about`	Show project information	`./binder about`
`help`	Show help information	`./binder help`

🚀 Shortcuts

All commands have convenient shortcuts:

Shortcut	Command
`b`	`build`
`p`	`preview`
`pdf`	`pdf`
`epub`	`epub`
`l`	`list`
`s`	`status`
`d`	`doctor`
`h`	`help`

Chapter Names

Chapters can be referenced by their short names. Common examples:

intro → Introduction chapter
ml_systems → Machine Learning Systems chapter
dl_primer → Deep Learning Primer chapter
training → Training chapter
ops → MLOps chapter

Use ./binder list to see all available chapters.

Build Outputs

Format	Output Location	Description
HTML	`build/html/`	Website format with navigation
PDF	`build/pdf/`	Academic book format

🚀 Publishing

The publish command provides two modes based on how you call it:

1. Interactive Mode (Default)

When called without arguments, publish runs the interactive wizard:

# Interactive publishing wizard
./binder publish

What interactive mode does:

🔍 Pre-flight checks - Verifies git status and branch
🧹 Cleans - Removes previous builds
📚 Builds HTML - Creates web version
📄 Builds PDF - Creates downloadable version
📦 Copies PDF - Moves PDF to assets directory
💾 Commits - Adds PDF to git
🚀 Pushes - Triggers GitHub Actions deployment

2. Command-Line Trigger Mode

When called with arguments, publish triggers the GitHub Actions workflow directly:

# Trigger GitHub Actions workflow
./binder publish "Description" [COMMIT_HASH]

# With options
./binder publish "Add new chapter" abc123def --type patch --no-ai

What command-line mode does:

🔍 Validates environment - Checks GitHub CLI, authentication, branch
✅ Validates commit - Ensures the dev commit exists (if provided)
🚀 Triggers workflow - Uses GitHub CLI to trigger the publish-live workflow
📊 Provides feedback - Shows monitoring links and next steps

Options:

--type patch|minor|major - Release type (default: minor)
--no-ai - Disable AI release notes
--yes - Skip confirmation prompts

Requirements:

GitHub CLI installed and authenticated (gh auth login)
Must be on main or dev branch
Dev commit must exist (if provided)

Publishing Workflow:

# Development workflow
./binder preview intro          # Preview a chapter
./binder build                  # Build complete HTML
./binder pdf                    # Build complete PDF
./binder publish                # Publish to the world

After Publishing:

🌐 Web version: Available at https://harvard-edge.github.io/cs249r_book
📄 PDF download: Available at https://harvard-edge.github.io/cs249r_book/assets/downloads/Machine-Learning-Systems.pdf
📈 GitHub Actions: Monitors build progress at https://github.com/harvard-edge/cs249r_book/actions

Requirements:

Must be on main branch
No uncommitted changes
Git repository properly configured

Advanced Features

Unified Multi-Chapter Builds

The binder supports building multiple chapters together in a single Quarto render command:

# Build multiple chapters together (HTML)
./binder build intro,ml_systems

# Build multiple chapters together (PDF)
./binder pdf intro,ml_systems

# Preview multiple chapters together
./binder preview intro,ml_systems

Benefits:

✅ Faster builds: Single Quarto process instead of multiple
✅ Shared context: Dependencies loaded once
✅ Unified processing: Cross-references and quizzes processed together
✅ Better UX: Single browser window opens with complete site

Fast Build Mode

Fast builds use selective rendering to only build essential files plus target chapters:

HTML Fast Build (project.render):

render:
  - index.qmd
  - 404.qmd
  - contents/frontmatter/
  - contents/core/target-chapter.qmd

PDF Fast Build (comments out unused chapters):

chapters:
  - index.qmd
  - contents/frontmatter/foreword.qmd
  - contents/core/target-chapter.qmd
  # - contents/core/other-chapter.qmd  # Commented for fast build

Selective PDF Chapter Building

When you run ./binder pdf intro, the system automatically:

Creates a backup of the original PDF configuration
Comments out all chapters except the target chapter and essential files
Builds only the selected content:
- ✅ index.qmd (always included)
- ✅ contents/core/introduction/introduction.qmd (target chapter)
- ❌ contents/backmatter/glossary/glossary.qmd (commented out)
- ❌ contents/backmatter/references.qmd (commented out)
Restores the original configuration after build completion

Example output:

./binder pdf intro

📄 Building chapter(s) as PDF: intro
🚀 Building 1 chapters (pdf)
⚡ Setting up fast build mode...
📋 Files to build: 2 files
✓ - index.qmd
✓ - contents/core/introduction/introduction.qmd
✓ Fast build mode configured (PDF/EPUB)

This ensures that in Binder environments, you get exactly what you need: a PDF containing only the index and your target chapter, with all other chapters automatically commented out during the build process.

Cloud Binder Compatibility

The selective PDF build system works seamlessly in cloud environments like mybinder.org:

For cloud Binder users:

# In a Jupyter terminal or notebook cell
!./binder pdf intro

# Or using the Python CLI directly
!python binder pdf intro

Key benefits for cloud environments:

✅ Reduced memory usage - Only builds essential chapters
✅ Faster build times - Skips unnecessary content
✅ Automatic cleanup - Restores configuration after build
✅ No manual editing - Everything is automated

What gets built:

Always includes index.qmd for proper book structure
Includes your target chapter (e.g., introduction.qmd)
Comments out all other chapters automatically
Comments out backmatter (glossary, references) for minimal builds

Configuration Management

The binder automatically manages Quarto configurations:

_quarto-html.yml: Website build configuration
_quarto-pdf.yml: Academic PDF build configuration
_quarto.yml: Symlink to active configuration (currently → config/_quarto-html.yml)

Important: The _quarto.yml file is a symlink that points to the active configuration. This allows the binder to quickly switch between HTML and PDF build modes without copying files.

Quarto Executable: The system quarto executable (/Applications/quarto/bin/quarto) is NOT a symlink - it's a regular executable file.

Use ./binder switch <format> to change the active configuration symlink.

Development Workflow

Typical Chapter Development

# 1. Start development on a chapter
./binder preview intro

# 2. Make edits, save files (auto-rebuild in preview mode)

# 3. Build multiple related chapters together
./binder build intro,ml_systems html

# 4. Check full book before committing
./binder build * pdf

Before Committing

# Clean up any build artifacts
./binder clean

# Run health check
./binder doctor

# Build full book to ensure everything works
./binder build
./binder pdf

Troubleshooting

Common Issues

"Chapter not found"

Use ./binder list to see available chapters
Check that the chapter QMD file exists
Verify the chapter path in configuration files

"Build artifacts detected"

Run ./binder clean to remove temporary files
Use ./binder doctor to verify system health

"Config not clean"

The binder detected a previous fast build configuration
Run ./binder clean to restore normal configuration

"Symlink issues"

If _quarto.yml is not a symlink: ln -sf config/_quarto-html.yml book/_quarto.yml
Check current symlink target: ls -la book/_quarto.yml
The symlink should point to either config/_quarto-html.yml or config/_quarto-pdf.yml

Performance Tips

Use fast builds (./binder build chapter html) for development
Use unified builds (./binder build ch1,ch2 html) for multiple chapters
Only use full builds (./binder build * format) for final verification
Preview mode auto-rebuilds on file changes

🚀 Publishing

The publish command provides a complete publishing workflow:

# One-command publishing
./binder publish

What it does:

Validates environment - Checks Git status, tools, and dependencies
Manages branches - Merges dev to main with confirmation
Plans release - Suggests version bump (patch/minor/major)
Builds everything - PDF first, then HTML (ensures PDF is available)
Creates release - Git tag, AI-generated release notes, GitHub release
Deploys - Copies PDF to assets, commits, pushes to production

Features:

🤖 AI-powered release notes (requires Ollama)
📊 Smart version suggestions based on changes
🛡️ Safety checks and confirmations
🎯 Step-by-step wizard with clear progress

For more details, see:

BUILD.md - Complete build instructions
DEVELOPMENT.md - Development setup and workflow

12 KiB Raw Blame History

Book Binder CLI

Quick Start

Installation

Command Reference

⚡ Core Commands

📚 Full Book Examples

🔧 Management Commands

🚀 Shortcuts

Chapter Names

Build Outputs

🚀 Publishing

1. Interactive Mode (Default)

2. Command-Line Trigger Mode

Publishing Workflow:

After Publishing:

Requirements:

Advanced Features

Unified Multi-Chapter Builds

Fast Build Mode

Selective PDF Chapter Building

Cloud Binder Compatibility

Configuration Management

Development Workflow

Typical Chapter Development

Before Committing

Troubleshooting

Common Issues

Performance Tips

🚀 Publishing

12 KiB

Raw Blame History