Add EPUB support to dual-config build system

- Create _quarto-epub.yml optimized for e-readers - Add EPUB build step to GitHub workflows - Include EPUB verification and artifact upload - Add epub format to controller build matrix - Output to build/epub/ directory - Compatible with binder CLI approach
2026-04-29 17:20:21 -05:00 · 2025-07-29 00:39:10 -04:00
parent f9a40a86ed
commit 90e3f8e433
3 changed files with 271 additions and 3 deletions
--- a/.github/workflows/controller.yml
+++ b/.github/workflows/controller.yml
@@ -50,7 +50,7 @@ jobs:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
-        format: [html, pdf]
+        format: [html, pdf, epub]
    uses: ./.github/workflows/quarto-build.yml
    with:
      environment: development
@@ -69,7 +69,7 @@ jobs:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
-        format: [html, pdf]
+        format: [html, pdf, epub]
    uses: ./.github/workflows/quarto-build.yml
    with:
      environment: production
--- a/.github/workflows/quarto-build.yml
+++ b/.github/workflows/quarto-build.yml
@@ -342,7 +342,19 @@ jobs:
          echo "✅ Configuration set to PDF"
          
          echo "🔨 Building PDF..."
-          quarto render --to titlepage-pdf     
+          quarto render --to titlepage-pdf
+
+      - name: 🔨 Build EPUB (copy config and render)
+        if: inputs.format == 'epub' || inputs.format == 'all'
+        shell: bash
+        run: |
+          echo "🚀 Setting up EPUB configuration..."
+          cd book
+          cp _quarto-epub.yml _quarto.yml
+          echo "✅ Configuration set to EPUB"
+          
+          echo "🔨 Building EPUB..."
+          quarto render --to epub     
      
      - name: 📋 Check Quarto Build Output
        shell: bash
@@ -383,6 +395,27 @@ jobs:
            fi
          fi

+          # EPUB check
+          if [[ "${{ inputs.format }}" == "epub" || "${{ inputs.format }}" == "all" ]]; then
+            if [ -d "build/epub" ]; then
+              echo "✅ build/epub directory exists"
+              echo "📊 Files in build/epub directory:"
+              ls -la build/epub | head -n 20
+              echo "📊 Total files in build/epub:"
+              find build/epub -type f | wc -l
+              
+              if [ -f "build/epub/Machine-Learning-Systems.epub" ]; then
+                echo "✅ EPUB file exists"
+                echo "📊 EPUB file size:"
+                du -h "build/epub/Machine-Learning-Systems.epub"
+              else
+                echo "⚠️ EPUB file not found!"
+              fi
+            else
+              echo "❌ build/epub directory not found!"
+            fi
+          fi
+
      - name: 📉 Compress PDF with Ghostscript (Linux)
        if: runner.os == 'Linux' && (inputs.format == 'pdf' || inputs.format == 'all')
        run: |
@@ -438,6 +471,7 @@ jobs:
          path: |
            build/html
            build/pdf
+            build/epub

      - name: 🚀 Stage to Dev Site
        if: inputs.target == 'dev' && inputs.deploy == true && inputs.format == 'html' && runner.os == 'Linux'
--- a/book/_quarto-epub.yml
+++ b/book/_quarto-epub.yml
@@ -0,0 +1,234 @@
+# =============================================================================
+# EPUB CONFIGURATION
+# =============================================================================
+# This configuration is optimized for EPUB e-book output.
+#
+# Key Features:
+# - Book project type with linear chapter flow
+# - EPUB-specific formatting and navigation
+# - Optimized for e-readers and mobile devices
+# - Clean typography without complex layouts
+#
+# Usage:
+#   ./binder build * epub     # Uses this config via symlink
+#
+# Part of the dual-configuration system:
+#   _quarto-html.yml   # Website optimized
+#   _quarto-pdf.yml    # Academic PDF optimized  
+#   _quarto-epub.yml   # This file (EPUB optimized)
+# =============================================================================
+
+project:
+  type: book
+  output-dir: ../build/epub
+  preview:
+    browser: true
+    navigate: true
+
+book:
+  favicon: assets/images/icons/favicon.png
+  cover-image: assets/images/covers/cover-hardcover-book.png
+  cover-image-alt: "Cover image."
+
+  title: "Machine Learning Systems"
+  subtitle: "Principles and Practices of Engineering Artificially Intelligent Systems"
+
+  date: today
+  date-format: long
+
+  author:
+    name: Vijay Janapa Reddi
+    email: vj@eecs.harvard.edu
+    url: https://www.google.com/search?q=Vijay+Janapa+Reddi
+    affiliations: Harvard University
+    corresponding: true
+    roles: "Author, editor and curator."
+
+  abstract: |
+    Machine Learning Systems presents a comprehensive approach to understanding and engineering machine learning (ML). While many resources focus on ML algorithms and model architectures, this book serves as a bridge between theoretical foundations and practical engineering. It emphasizes the systems context that engineers need to master when building AI solutions in the real world.
+
+  repo-url: https://github.com/harvard-edge/cs249r_book
+  repo-branch: widget_quiz
+
+  page-footer:
+    left: |
+      Written, edited and curated by Prof. Vijay Janapa Reddi (Harvard University)
+    right: |
+      This book was built with <a href="https://quarto.org/">Quarto</a>.
+
+  chapters:
+    - index.qmd
+    - contents/frontmatter/foreword.qmd
+    - contents/frontmatter/about/about.qmd
+    - contents/frontmatter/acknowledgements/acknowledgements.qmd
+
+    # Systems Foundations
+    - contents/core/introduction/introduction.qmd
+    - contents/core/ml_systems/ml_systems.qmd
+    - contents/core/dl_primer/dl_primer.qmd
+    - contents/core/dnn_architectures/dnn_architectures.qmd
+
+    # Design Principles
+    - contents/core/workflow/workflow.qmd
+    - contents/core/data_engineering/data_engineering.qmd
+    - contents/core/frameworks/frameworks.qmd
+    - contents/core/training/training.qmd
+
+    # Performance Engineering
+    - contents/core/efficient_ai/efficient_ai.qmd
+    - contents/core/optimizations/optimizations.qmd
+    - contents/core/hw_acceleration/hw_acceleration.qmd
+    - contents/core/benchmarking/benchmarking.qmd
+
+    # Robust Deployment
+    - contents/core/ops/ops.qmd
+    - contents/core/ondevice_learning/ondevice_learning.qmd
+    - contents/core/robust_ai/robust_ai.qmd
+    - contents/core/privacy_security/privacy_security.qmd
+
+    # Ethical AI Systems
+    - contents/core/responsible_ai/responsible_ai.qmd
+    - contents/core/sustainable_ai/sustainable_ai.qmd
+    - contents/core/ai_for_good/ai_for_good.qmd
+
+    # Frontiers
+    - contents/core/emerging_topics/emerging_topics.qmd
+    - contents/core/conclusion/conclusion.qmd
+
+    # Labs
+    - contents/labs/labs.qmd
+    - contents/labs/kits.qmd
+    - contents/labs/ide_setup.qmd
+
+    # Arduino Labs
+    - contents/labs/arduino/nicla_vision/nicla_vision.qmd
+    - contents/labs/arduino/nicla_vision/setup/setup.qmd
+    - contents/labs/arduino/nicla_vision/image_classification/image_classification.qmd
+    - contents/labs/arduino/nicla_vision/object_detection/object_detection.qmd
+    - contents/labs/arduino/nicla_vision/kws/kws.qmd
+    - contents/labs/arduino/nicla_vision/motion_classification/motion_classification.qmd
+
+    # Seeed XIAO ESP32S3 Labs
+    - contents/labs/seeed/xiao_esp32s3/xiao_esp32s3.qmd
+    - contents/labs/seeed/xiao_esp32s3/setup/setup.qmd
+    - contents/labs/seeed/xiao_esp32s3/image_classification/image_classification.qmd
+    - contents/labs/seeed/xiao_esp32s3/object_detection/object_detection.qmd
+    - contents/labs/seeed/xiao_esp32s3/kws/kws.qmd
+    - contents/labs/seeed/xiao_esp32s3/motion_classification/motion_classification.qmd
+
+    # Grove Vision Labs
+    - contents/labs/seeed/grove_vision_ai_v2/grove_vision_ai_v2.qmd
+    - contents/labs/seeed/grove_vision_ai_v2/setup_and_no_code_apps/setup_and_no_code_apps.qmd
+    - contents/labs/seeed/grove_vision_ai_v2/image_classification/image_classification.qmd
+    - contents/labs/seeed/grove_vision_ai_v2/object_detection/object_detection.qmd
+
+    # Raspberry Pi Labs
+    - contents/labs/raspi/raspi.qmd
+    - contents/labs/raspi/setup/setup.qmd
+    - contents/labs/raspi/image_classification/image_classification.qmd
+    - contents/labs/raspi/object_detection/object_detection.qmd
+    - contents/labs/raspi/llm/llm.qmd
+    - contents/labs/raspi/vlm/vlm.qmd
+
+    # Shared Labs
+    - contents/labs/shared/shared.qmd
+    - contents/labs/shared/kws_feature_eng/kws_feature_eng.qmd
+    - contents/labs/shared/dsp_spectral_features_block/dsp_spectral_features_block.qmd
+
+    # Backmatter
+    - contents/backmatter/references.qmd
+    - contents/backmatter/resources/phd_survival_guide.qmd
+
+bibliography:
+  - contents/core/introduction/introduction.bib
+  - contents/core/ai_for_good/ai_for_good.bib
+  - contents/core/benchmarking/benchmarking.bib
+  - contents/core/data_engineering/data_engineering.bib
+  - contents/core/dl_primer/dl_primer.bib
+  - contents/core/dnn_architectures/dnn_architectures.bib
+  - contents/core/efficient_ai/efficient_ai.bib
+  - contents/core/ml_systems/ml_systems.bib
+  - contents/core/frameworks/frameworks.bib
+  - contents/core/hw_acceleration/hw_acceleration.bib
+  - contents/core/ondevice_learning/ondevice_learning.bib
+  - contents/core/ops/ops.bib
+  - contents/core/optimizations/optimizations.bib
+  - contents/core/privacy_security/privacy_security.bib
+  - contents/core/responsible_ai/responsible_ai.bib
+  - contents/core/robust_ai/robust_ai.bib
+  - contents/core/sustainable_ai/sustainable_ai.bib
+  - contents/core/training/training.bib
+  - contents/core/workflow/workflow.bib
+  - contents/core/conclusion/conclusion.bib
+
+crossref:
+  appendix-title: "Appendix"
+  appendix-delim: ":"
+
+citation: true
+license: CC-BY-NC-SA
+
+# Minimal filters for EPUB (avoid complex layouts)
+filters:
+  - ../config/lua/inject_quizzes.lua
+  - ../config/lua/inject_crossrefs.lua
+
+# Filter configurations and metadata
+filter-metadata:
+  # Quiz configuration for inject_quizzes.lua filter
+  quiz-config:
+    file-pattern: "*_quizzes.json"
+    scan-directory: "contents/core"
+    auto-discover-pdf: false
+
+  # Cross-reference injection configuration for inject_crossrefs.lua filter  
+  cross-references:
+    file: "data/cross_refs_final.json"
+    enabled: true
+
+editor:
+  render-on-save: true
+
+format:
+  epub:
+    cover-image: assets/images/covers/cover-hardcover-book.png
+    epub-chapter-level: 1
+    epub-title-page: true
+    epub-metadata: |
+      <dc:subject>Machine Learning</dc:subject>
+      <dc:subject>Systems Engineering</dc:subject>
+      <dc:subject>Artificial Intelligence</dc:subject>
+      <dc:subject>Computer Science</dc:subject>
+      <dc:description>A comprehensive guide to building machine learning systems from theory to practice.</dc:description>
+    
+    toc: true
+    toc-depth: 3
+    number-sections: true
+    number-depth: 3
+    
+    # Citations and references
+    cite-method: citeproc
+    reference-location: block
+    citation-location: block
+    
+    # Typography optimized for e-readers
+    fontsize: 12pt
+    lineheight: 1.6
+    
+    # Keep it simple for EPUB compatibility
+    link-citations: true
+    colorlinks: false
+    
+    # Figure settings
+    fig-width: 6
+    fig-height: 4
+    fig-caption: true
+    fig-cap-location: bottom
+    
+    # Table settings
+    tbl-cap-location: top
+    tbl-colwidths: auto
+
+resources:
+  - CNAME
+  - assets