Notebooks use short names (tensor.ipynb, not 01_tensor.ipynb) but docs
and Binder postBuild scripts used the prefixed form. This caused broken
Binder links and incorrect paths in troubleshooting guides.
Fixes: harvard-edge/cs249r_book#1176
* Restructure: Move book content to book/ subdirectory
- Move quarto/ → book/quarto/
- Move cli/ → book/cli/
- Move docker/ → book/docker/
- Move socratiQ/ → book/socratiQ/
- Move tools/ → book/tools/
- Move scripts/ → book/scripts/
- Move config/ → book/config/
- Move docs/ → book/docs/
- Move binder → book/binder
Git history fully preserved for all moved files.
Part of repository restructuring to support MLSysBook + TinyTorch.
Pre-commit hooks bypassed for this commit as paths need updating.
* Update pre-commit hooks for book/ subdirectory
- Update all quarto/ paths to book/quarto/
- Update all tools/ paths to book/tools/
- Update config/linting to book/config/linting
- Update project structure checks
Pre-commit hooks will now work with new directory structure.
* Update .gitignore for book/ subdirectory structure
- Update quarto/ paths to book/quarto/
- Update assets/ paths to book/quarto/assets/
- Maintain all existing ignore patterns
* Update GitHub workflows for book/ subdirectory
- Update all quarto/ paths to book/quarto/
- Update cli/ paths to book/cli/
- Update tools/ paths to book/tools/
- Update docker/ paths to book/docker/
- Update config/ paths to book/config/
- Maintain all workflow functionality
* Update CLI config to support book/ subdirectory
- Check for book/quarto/ path first
- Fall back to quarto/ for backward compatibility
- Maintain full CLI functionality
* Create new root and book READMEs for dual structure
- Add comprehensive root README explaining both projects
- Create book-specific README with quick start guide
- Document repository structure and navigation
- Prepare for TinyTorch integration
🔧 Restored Critical Commands:
- clean: Clean build artifacts and restore configs
- switch: Switch active configuration format
- setup: Setup development environment
- hello: Show welcome message and quick start
- about: Show project information and stats
- check: Check for build artifacts (legacy compatibility)
- check-tags: Check for orphaned git tags
✨ New Modular Architecture:
- CleanCommand: Handles artifact cleanup and config restoration
- MaintenanceCommand: Handles setup, switch, hello, about operations
- All commands properly integrated into main CLI
🎯 Feature Parity Achieved:
- All original binder functionality restored
- Enhanced with better error handling
- Improved user experience with Rich UI
- Modular design for easy maintenance
The CLI migration is now 100% complete with full feature parity
New Commands:
- Add PreviewCommand for live development server with hot reload
- Add DoctorCommand for comprehensive health checks (18 checks)
- Clear command descriptions distinguish build vs preview vs formats
Command Clarity:
- build: Build static files to disk (HTML)
- preview: Start live dev server with hot reload
- pdf: Build static PDF file to disk
- epub: Build static EPUB file to disk
Health Check Features:
- System dependencies (Python, Quarto, Git, Node.js, R)
- Configuration file validation
- Chapter file scanning (62 chapters found)
- Build artifacts status
- Git repository status
- File permissions check
All tests passing - comprehensive CLI ready for use
Refactors the CLI to streamline command usage, making it more intuitive.
It simplifies the build process by introducing default behaviors
and removing unnecessary format specifications. Also introduces 'pdf' command
to build the book in PDF format.
This change enhances the user experience and improves the overall workflow.
- Add EPUB format support with config/_quarto-epub.yml configuration
- Simplify build command: './binder build <format>' instead of './binder build <chapters> <format>'
- Improve preview command to support multiple chapters: './binder preview intro,ops'
- Update help text and examples to reflect new simplified interface
- Remove unnecessary config cleaning steps for better performance
- Add proper render target mapping for EPUB format
This streamlines the CLI interface and adds missing EPUB build capability.
Simplifies frontmatter inclusion logic to retain only
'index.qmd' when building single chapter books,
removing unnecessary checks for other frontmatter files.
Relocates the PDF file to the /assets/downloads directory to better organize assets.
Updates all links and redirects to point to the new PDF location, ensuring consistent access throughout the site.
Simplifies the deployment process by directly copying the PDF to the correct location during the build, removing unnecessary steps.
Improves the website deployment process by adding comprehensive information, validation steps, and clearer feedback to the user.
Provides detailed descriptions of the deployment process, estimated timelines, and quality checks.
Introduces an "info" option for users to get in-depth details about the publishing workflow.
The changes increase transparency and control over the deployment process, reduce user errors, and increases user confidence.
- Add PDF existence and size validation in _deploy_to_github_pages
- Add build validation in _execute_build_phase to ensure both HTML and PDF are ready
- Validate PDF file size (minimum 1MB) to catch corrupted/incomplete builds
- Add copy validation to ensure PDF is properly copied to assets directory
- Fail fast with clear error messages if builds are not ready
- Ensure deployment stops before GitHub Pages if PDF is missing
- Add main branch validation for ./binder publish
- Add main branch validation for ./binder release
- Both commands now require main branch for safety
- Provide interactive branch switching with commit handling
- Ensure user-facing operations are always from stable main branch
- Add comprehensive release process documentation for academic textbook
- Update AI prompt to generate textbook-appropriate release notes
- Enhance version guide with examples specific to textbook releases
- Focus on educational content, chapters, and student-facing improvements
This establishes clean release practices going forward with proper
semantic versioning for textbook milestones.
Major architectural improvement: The binder tool now reads output directories
directly from Quarto YAML configuration files instead of hardcoding paths.
Key changes:
- Add get_output_dir() method to parse output-dir from _quarto-html.yml and _quarto-pdf.yml
- Replace all hardcoded self.build_dir references with dynamic get_output_dir() calls
- Update GitHub Pages deployment to use dynamic paths
- Update build completion messages to show actual output locations
- Update clean/check artifact detection to use dynamic paths
- Add YAML parsing with graceful fallback to defaults
Benefits:
- Eliminates configuration drift between binder and Quarto configs
- Supports flexible output directory structures
- Makes binder tool truly config-driven and maintainable
- Provides better debugging with actual path information
- Move build output from root/build/ to quarto/_build/
- Update Quarto configs to output-dir: _build/html and _build/pdf
- Update binder tool to use new build directory location
- Update clean and check methods for new artifact locations
- Add quarto/_build/ to .gitignore
- Remove old build/ directory
This makes more architectural sense as builds are now co-located
with the Quarto project files, and eliminates the cross-directory
dependency that was causing GitHub Pages deployment issues.
Solves critical version management issue where failed publishes
leave orphaned git tags that cause version numbering problems.
New features:
- Automatic detection of git tags without GitHub releases
- Interactive cleanup options (clean all, manual selection, etc.)
- Smart version calculation that accounts for orphaned tags
- New 'check-tags' command for standalone tag management
- Detailed tag information display (creation date, commit info)
- Safe cleanup with confirmation prompts
Prevents version increment issues when previous publishes fail
after creating git tags but before completing GitHub releases.
Solves critical version management issue where failed publishes
leave orphaned git tags that cause version numbering problems.
New features:
- Automatic detection of git tags without GitHub releases
- Interactive cleanup options (clean all, manual selection, etc.)
- Smart version calculation that accounts for orphaned tags
- New 'check-tags' command for standalone tag management
- Detailed tag information display (creation date, commit info)
- Safe cleanup with confirmation prompts
Prevents version increment issues when previous publishes fail
after creating git tags but before completing GitHub releases.
Remove redundant local subprocess imports that were causing
'cannot access local variable subprocess' error. subprocess
is already imported globally at the top of the file.
Remove redundant local subprocess imports that were causing
'cannot access local variable subprocess' error. subprocess
is already imported globally at the top of the file.
Complete the standardization of user prompts by adding clear
options and default value display to the PDF compression prompt
in the build workflow to match the publishing workflow format.
- Standardize all prompts to show available options with explanations
- Add clear default values in format [default: X]
- Enhance release notes review with preview and multiple options
- Improve branch switching, compression, and publishing prompts
- Add color-coded option descriptions for better UX
- Handle empty input gracefully by using specified defaults
All prompts now provide clear guidance on what each option does
and what the recommended choice is.
- Save AI-generated release notes to temporary markdown file
- Prompt user to review and edit release notes before publishing
- Offer to open file in default system editor automatically
- Read edited content back for GitHub release creation
- Clean up temporary file after successful release
- Update publish help documentation with new workflow
- Enhance example session to show editing step
- Cross-platform editor support for macOS, Linux, Windows
- Add comprehensive version type guidance (patch/minor/major/custom)
- Improve spacing and line breaks throughout publishing flow
- Add helpful explanations for GitHub Pages and release creation
- Enhance confirmation dialogs with clear action descriptions
- Add contextual prompts explaining what each choice does
- Show version transitions (Previous → New) for clarity
- Provide skip confirmations for optional deployment steps
- Integrate complete manual publishing workflow directly into binder
- Add AI-enhanced release notes generation using Ollama
- Implement PDF-first build order with Ghostscript compression
- Add intelligent branch management with dev-to-main workflow
- Generate GitHub-style git logs between versions
- Combine AI summaries with raw commit information
- Maintain clean single entry point interface (binder publish)
- Add comprehensive error handling and graceful fallbacks
- Include rich UI with progress indicators and clear messaging
- Support PDF compression with ebook settings for distribution
- Modified publish-live workflow to download PDF from artifacts and upload to release assets
- Updated quarto-build deployment to copy PDF to assets but exclude from git commits
- Added PDF exclusion rules to .gitignore
- Removed PDF commit steps from publish.sh and binder scripts
- Created test script to verify PDF handling
- Added comprehensive documentation for the new workflow
This ensures PDF is available for download but not tracked in git repository,
keeping the repo clean while maintaining accessibility.
Updates prompts to use uppercase 'Y' as the default
affirmative response, improving clarity for users.
The changes ensures consistency and better UX across various prompts
related to merging, release creation, AI release notes,
changelog updates and git config.
- Remove ASCII art for cleaner, simpler interface
- Keep nerdy subtitle: '⚡ I compile ML systems knowledge'
- Simplify banner and about screen
- Maintain professional, clean appearance
- Add ./binder publish command with confirmation
- Add ./binder about command with system status
- Add beautiful ASCII art with proper alignment
- Add nerdy subtitle: 'I compile ML systems knowledge for the world'
- Improve help and shortcuts (add 'a' for about, 'pub' for publish)
- Add confirmation warning for publishing
- Update documentation to reflect new commands
Addresses minor visual inconsistencies in console output by adjusting the spacing before the hammer emoji.
Improves the overall user experience by providing cleaner and more visually appealing output during build processes.
Refines the build output by adjusting the indentation for better readability.
The change adds a single space to the beginning of the build messages, improving their visual alignment in the console.
