mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-03-11 17:49:25 -05:00
c30f2a3bfd
Moves the mlsysim package from book/quarto/mlsysim/ to the repo root so it is importable as a proper top-level package across the codebase. Key changes: - mlsysim/fmt.py: new top-level module for all formatting helpers (fmt, sci, check, md_math, fmt_full, fmt_split, etc.), moved out of viz/ - mlsysim/viz/__init__.py: now exports only plot utilities; dashboard.py (marimo-only) is no longer wildcard-exported and must be imported explicitly by marimo labs - mlsysim/__init__.py: added `from . import fmt` and `from .core import constants`; removed broken `from .viz import plots as viz` alias - execute-env.yml: fixed PYTHONPATH from "../../.." to "../.." so chapters resolve to repo root, not parent of repo - 51 QMD files: updated `from mlsysim.viz import <fmt-fns>` to `from mlsysim.fmt import <fmt-fns>` - book/quarto/mlsys/: legacy shadow package contents cleaned up; stub __init__.py remains for backward compat - All Vol1 and Vol2 chapters verified to build with `binder build pdf`
MLSysBook CLI v2.0 - Modular Architecture
This directory contains the refactored, modular CLI for the MLSysBook project. The CLI has been broken down from a monolithic 4000+ line script into maintainable, testable modules.
Architecture
cli/
├── __init__.py # Package initialization
├── main.py # Main CLI application class
├── core/ # Core functionality
│ ├── config.py # Configuration management
│ └── discovery.py # Chapter/file discovery
├── commands/ # Command implementations
│ └── build.py # Build operations
├── formats/ # Format-specific handlers (future)
└── utils/ # Shared utilities (future)
Key Components
ConfigManager (core/config.py)
- Manages Quarto configuration files for HTML, PDF, and EPUB
- Handles symlink creation and switching between formats
- Provides output directory detection from config files
ChapterDiscovery (core/discovery.py)
- Discovers and validates chapter files
- Supports fuzzy matching for chapter names
- Provides chapter listing and dependency detection
BuildCommand (commands/build.py)
- Handles build operations for all formats
- Supports both full book and individual chapter builds
- Includes progress indication and error handling
MLSysBookCLI (main.py)
- Main application class that orchestrates all components
- Provides command routing and help system
- Beautiful Rich-based UI with organized command tables
Usage
The modular CLI has replaced the original binder and is available as ./binder in the project root:
# Show help
./binder help
# Build commands
./binder build # Build full book (HTML)
./binder build intro,ml_systems # Build specific chapters (HTML)
./binder build pdf intro # Build chapter as PDF
./binder build epub # Build full book as EPUB
# Preview commands
./binder preview # Start live dev server for full book
./binder preview intro # Start live dev server for chapter
# Management
./binder list # List all chapters
./binder status # Show current status
./binder doctor # Run comprehensive health check
Benefits of Modular Architecture
- Maintainability: Each component has a single responsibility
- Testability: Individual modules can be unit tested
- Debuggability: Issues can be isolated to specific modules
- Extensibility: New formats and commands are easy to add
- Code Reuse: Shared functionality is properly modularized
- Collaboration: Multiple developers can work on different components
Migration Complete
The modular CLI has successfully replaced the original monolithic binder script:
./binder- Modular CLI (4000+ lines → organized modules)
All functionality has been preserved and enhanced:
- All existing commands work the same way
- Same configuration files and output directories
- Same build processes and quality
- Enhanced error handling and progress indication
- New preview and doctor commands added
Future Enhancements
The modular architecture enables easy addition of:
- Format-specific handlers in
formats/ - Additional commands in
commands/ - Shared utilities in
utils/ - Plugin system for custom extensions
- Comprehensive unit test suite