mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-04-30 01:29:07 -05:00
dcc8afb4cc
- debugCommands: prompt for format (PDF, HTML, EPUB) in Build All Chapters (Parallel) - parallelDebug: clearer success/fail messages, Open Reports Folder, REPORT.md header - README: document volume + format selection for parallel builds
89 lines
4.4 KiB
Markdown
89 lines
4.4 KiB
Markdown
# MLSysBook VS Code Extension
|
||
|
||
The MLSysBook extension provides editor-first workflows for building, debugging, and validating the book without leaving VS Code.
|
||
|
||
## Loading the extension (so you see the latest code)
|
||
|
||
The editor runs **one** copy of the extension. Reload only reloads that copy. If that copy isn’t from this repo, you won’t see new changes (e.g. Reset Quarto config) until you point the editor at this repo’s extension.
|
||
|
||
**Option A – Run from repo (recommended when developing)**
|
||
1. Open the **repo root** (`mlsysbook-vols`) in Cursor/VS Code.
|
||
2. Run **`npm run compile`** in `book/vscode-ext` (or run it from the repo root: `cd book/vscode-ext && npm run compile`).
|
||
3. Press **F5** (or Run → Start Debugging → “Run MLSysBook Extension”).
|
||
4. A **new window** opens; that window is running the extension from `book/vscode-ext`. Use that window for the book (Reset, Build, etc.).
|
||
5. After code changes: run **compile** again, then in that new window use **Developer: Reload Window** so it picks up the new code.
|
||
|
||
**Option B – Install from this folder**
|
||
1. Command Palette → **Developer: Install Extension from Location…**
|
||
2. Choose the folder: **`mlsysbook-vols/book/vscode-ext`**.
|
||
3. Reload the window when prompted.
|
||
4. After code changes: run **`npm run compile`** in `book/vscode-ext`, then **Developer: Reload Window**. No need to install again unless you remove the extension.
|
||
|
||
## Binder-First Integration
|
||
|
||
This extension treats `./book/binder` as the operational backend.
|
||
|
||
- Build and debug commands execute Binder subcommands.
|
||
- Validation actions execute `binder validate ...`.
|
||
- Maintenance actions execute `binder maintain ...`.
|
||
|
||
## Work vs Configuration
|
||
|
||
The extension separates daily work from configuration:
|
||
|
||
- Work views: Build, Debug, Recent Runs, Navigator, Validate, Publish/Maintenance
|
||
- Configuration view: execution mode, navigator preset, visual preset, and extension settings
|
||
|
||
This keeps daily actions focused while preserving easy access to tuning controls.
|
||
|
||
## Why This Matters
|
||
|
||
- One public CLI contract for terminal, extension, and CI.
|
||
- Reduced drift between script behavior and editor behavior.
|
||
- Better diagnostics with optional machine-readable output (`--json`) from Binder validation.
|
||
|
||
## Core Workflows
|
||
|
||
- Build chapter: `./book/binder build html <chapter>` / `./book/binder build pdf <chapter>`
|
||
- Debug failures: `./book/binder debug <pdf|html|epub> --vol1|--vol2`
|
||
- Validate content: `./book/binder validate all`
|
||
- Maintenance checks: `./book/binder maintain repo-health`
|
||
|
||
## Parallel builds (Test All Chapters)
|
||
|
||
**Build All Chapters (Parallel)** in the Debug view runs each chapter in a separate git worktree so multiple builds run at once. You choose **volume** (Vol I / Vol II) and **format** (PDF, HTML, or EPUB).
|
||
|
||
**Requirements:**
|
||
|
||
1. **Open the repo root** — Open the folder that contains `book/` (e.g. `mlsysbook-vols`), not a subfolder like `book/` or `book/quarto/`. The extension needs `book/binder` to be present to register commands and run parallel jobs.
|
||
2. **Git in PATH** — Parallel mode uses `git worktree add --detach`; ensure `git` is available in the environment where the extension runs.
|
||
3. **Optional settings** (VS Code/Cursor → Settings → MLSysBook):
|
||
- `mlsysbook.parallelDebugWorkers` — number of concurrent builds (default: 4).
|
||
- `mlsysbook.parallelDebugRoot` — directory for worktrees under repo root (default: `.mlsysbook/worktrees`).
|
||
- `mlsysbook.keepFailedWorktrees` — keep worktrees for failed chapters for inspection (default: true).
|
||
|
||
If worktree creation fails, check the **MLSysBook Parallel Debug** output channel; the first failure will include a tip about repo root and git.
|
||
|
||
## Quarto Visual Customization
|
||
|
||
The extension includes QMD-focused visual highlighting to improve scanability in long Quarto documents.
|
||
|
||
Recommended baseline:
|
||
|
||
- `mlsysbook.enableQmdChunkHighlight = true`
|
||
- `mlsysbook.qmdVisualPreset = balanced`
|
||
- `mlsysbook.highlightInlineReferences = true`
|
||
- `mlsysbook.highlightLabelDefinitions = true`
|
||
- `mlsysbook.highlightDivFenceMarkers = true`
|
||
|
||
What gets emphasized:
|
||
|
||
- Inline references like `@fig-...`, `@tbl-...`, `@sec-...`
|
||
- Label definitions like `{#fig-...}` and `#| label: ...`
|
||
- Quarto div fence markers (`:::` / `::::`) and region blocks (callouts/divs/code fences)
|
||
|
||
## Notes
|
||
|
||
- Legacy script entrypoints still exist for compatibility in some areas.
|
||
- For Binder-covered tasks, direct script invocation is soft-deprecated.
|