mirror of
https://github.com/MLSysBook/TinyTorch.git
synced 2026-06-05 07:16:51 -05:00
build: add PDF generation infrastructure for book
Add build scripts and GitHub Actions workflow to support PDF generation: - build_pdf.sh: LaTeX-based PDF build for professional quality - build_pdf_simple.sh: HTML-to-PDF build without LaTeX requirement - Makefile: convenient shortcuts for common build tasks - GitHub Actions workflow: automated PDF builds on demand Supports multiple output formats: - HTML website (default, via jupyter-book) - PDF via HTML-to-PDF (pyppeteer, no LaTeX needed) - PDF via LaTeX (professional typography, requires LaTeX) Usage: make html - Build HTML website make pdf-simple - Build PDF without LaTeX make pdf - Build PDF with LaTeX
This commit is contained in:
100
.github/workflows/build-pdf.yml
vendored
Normal file
100
.github/workflows/build-pdf.yml
vendored
Normal file
@@ -0,0 +1,100 @@
|
||||
name: Build TinyTorch PDF
|
||||
|
||||
# Build PDF version of the book
|
||||
# Runs manually or on release tags
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
method:
|
||||
description: 'Build method (simple or latex)'
|
||||
required: true
|
||||
default: 'simple'
|
||||
type: choice
|
||||
options:
|
||||
- simple
|
||||
- latex
|
||||
release:
|
||||
types: [published]
|
||||
|
||||
jobs:
|
||||
build-pdf:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.11'
|
||||
cache: 'pip'
|
||||
|
||||
- name: Install base dependencies
|
||||
run: |
|
||||
pip install --upgrade pip
|
||||
pip install "jupyter-book<1.0"
|
||||
pip install -r book/requirements.txt
|
||||
|
||||
- name: Install LaTeX (if latex method)
|
||||
if: github.event.inputs.method == 'latex' || github.event_name == 'release'
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y \
|
||||
texlive-latex-extra \
|
||||
texlive-fonts-recommended \
|
||||
texlive-latex-recommended \
|
||||
latexmk
|
||||
|
||||
- name: Install pyppeteer (if simple method)
|
||||
if: github.event.inputs.method == 'simple' || github.event.inputs.method == ''
|
||||
run: |
|
||||
pip install pyppeteer
|
||||
# Pre-download Chromium to avoid timeout during build
|
||||
python -c "from pyppeteer import chromium_downloader; chromium_downloader.download_chromium()"
|
||||
|
||||
- name: Build PDF (simple method)
|
||||
if: github.event.inputs.method == 'simple' || github.event.inputs.method == ''
|
||||
run: |
|
||||
cd book
|
||||
jupyter-book clean . --all
|
||||
jupyter-book build . --builder pdfhtml
|
||||
# Copy to standard location
|
||||
mkdir -p _build/pdf-output
|
||||
cp _build/pdf/book.pdf _build/pdf-output/tinytorch-course.pdf
|
||||
|
||||
- name: Build PDF (LaTeX method)
|
||||
if: github.event.inputs.method == 'latex' || github.event_name == 'release'
|
||||
run: |
|
||||
cd book
|
||||
jupyter-book clean . --all
|
||||
jupyter-book build . --builder pdflatex
|
||||
# Copy to standard location
|
||||
mkdir -p _build/pdf-output
|
||||
cp _build/latex/tinytorch-course.pdf _build/pdf-output/tinytorch-course.pdf
|
||||
|
||||
- name: Upload PDF artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: tinytorch-pdf-${{ github.event.inputs.method || 'latex' }}-${{ github.sha }}
|
||||
path: book/_build/pdf-output/tinytorch-course.pdf
|
||||
retention-days: 90
|
||||
|
||||
- name: Upload to release (if release event)
|
||||
if: github.event_name == 'release'
|
||||
uses: softprops/action-gh-release@v1
|
||||
with:
|
||||
files: book/_build/pdf-output/tinytorch-course.pdf
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Build summary
|
||||
run: |
|
||||
echo "## 📚 PDF Build Complete" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**Method:** ${{ github.event.inputs.method || 'latex' }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**File:** tinytorch-course.pdf" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**Size:** $(du -h book/_build/pdf-output/tinytorch-course.pdf | cut -f1)" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "Download the PDF from the artifacts section above." >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
58
book/Makefile
Normal file
58
book/Makefile
Normal file
@@ -0,0 +1,58 @@
|
||||
# TinyTorch Book Build Makefile
|
||||
# Convenient shortcuts for building HTML and PDF versions
|
||||
|
||||
.PHONY: help html pdf pdf-simple clean install test
|
||||
|
||||
help:
|
||||
@echo "TinyTorch Book Build Commands"
|
||||
@echo "=============================="
|
||||
@echo ""
|
||||
@echo " make html - Build HTML version (default website)"
|
||||
@echo " make pdf - Build PDF via LaTeX (requires LaTeX installation)"
|
||||
@echo " make pdf-simple - Build PDF via HTML (no LaTeX required)"
|
||||
@echo " make clean - Remove all build artifacts"
|
||||
@echo " make install - Install Python dependencies"
|
||||
@echo " make install-pdf - Install dependencies for PDF building"
|
||||
@echo " make test - Test build configuration"
|
||||
@echo ""
|
||||
@echo "Quick start for PDF:"
|
||||
@echo " make install-pdf && make pdf-simple"
|
||||
@echo ""
|
||||
|
||||
html:
|
||||
@echo "🌐 Building HTML version..."
|
||||
jupyter-book build .
|
||||
|
||||
pdf:
|
||||
@echo "📚 Building PDF via LaTeX..."
|
||||
@./build_pdf.sh
|
||||
|
||||
pdf-simple:
|
||||
@echo "📚 Building PDF via HTML..."
|
||||
@./build_pdf_simple.sh
|
||||
|
||||
clean:
|
||||
@echo "🧹 Cleaning build artifacts..."
|
||||
jupyter-book clean . --all
|
||||
rm -rf _build/
|
||||
|
||||
install:
|
||||
@echo "📦 Installing base dependencies..."
|
||||
pip install -U pip
|
||||
pip install "jupyter-book<1.0"
|
||||
pip install -r requirements.txt
|
||||
|
||||
install-pdf:
|
||||
@echo "📦 Installing PDF dependencies..."
|
||||
pip install -U pip
|
||||
pip install "jupyter-book<1.0" pyppeteer
|
||||
pip install -r requirements.txt
|
||||
|
||||
test:
|
||||
@echo "🧪 Testing build configuration..."
|
||||
jupyter-book config sphinx .
|
||||
@echo "✅ Configuration valid"
|
||||
|
||||
# Default target
|
||||
.DEFAULT_GOAL := help
|
||||
|
||||
69
book/build_pdf.sh
Executable file
69
book/build_pdf.sh
Executable file
@@ -0,0 +1,69 @@
|
||||
#!/bin/bash
|
||||
# Build PDF version of TinyTorch book
|
||||
# This script builds the LaTeX/PDF version using jupyter-book
|
||||
|
||||
set -e # Exit on error
|
||||
|
||||
echo "🔥 Building TinyTorch PDF..."
|
||||
echo ""
|
||||
|
||||
# Check if we're in the book directory
|
||||
if [ ! -f "_config.yml" ]; then
|
||||
echo "❌ Error: Must run from book/ directory"
|
||||
echo "Usage: cd book && ./build_pdf.sh"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check dependencies
|
||||
echo "📋 Checking dependencies..."
|
||||
if ! command -v jupyter-book &> /dev/null; then
|
||||
echo "❌ Error: jupyter-book not installed"
|
||||
echo "Install with: pip install jupyter-book"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! command -v pdflatex &> /dev/null; then
|
||||
echo "⚠️ Warning: pdflatex not found"
|
||||
echo "PDF build requires LaTeX installation:"
|
||||
echo " - macOS: brew install --cask mactex-no-gui"
|
||||
echo " - Ubuntu: sudo apt-get install texlive-latex-extra texlive-fonts-recommended"
|
||||
echo " - Windows: Install MiKTeX from miktex.org"
|
||||
echo ""
|
||||
echo "Alternatively, use HTML-to-PDF build (doesn't require LaTeX):"
|
||||
echo " jupyter-book build . --builder pdfhtml"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Dependencies OK"
|
||||
echo ""
|
||||
|
||||
# Clean previous builds
|
||||
echo "🧹 Cleaning previous builds..."
|
||||
jupyter-book clean . --all || true
|
||||
echo ""
|
||||
|
||||
# Build PDF via LaTeX
|
||||
echo "📚 Building LaTeX/PDF (this may take a few minutes)..."
|
||||
jupyter-book build . --builder pdflatex
|
||||
|
||||
# Check if build succeeded
|
||||
if [ -f "_build/latex/tinytorch-course.pdf" ]; then
|
||||
PDF_SIZE=$(du -h "_build/latex/tinytorch-course.pdf" | cut -f1)
|
||||
echo ""
|
||||
echo "✅ PDF build complete!"
|
||||
echo "📄 Output: book/_build/latex/tinytorch-course.pdf"
|
||||
echo "📊 Size: ${PDF_SIZE}"
|
||||
echo ""
|
||||
echo "To view the PDF:"
|
||||
echo " open _build/latex/tinytorch-course.pdf # macOS"
|
||||
echo " xdg-open _build/latex/tinytorch-course.pdf # Linux"
|
||||
echo " start _build/latex/tinytorch-course.pdf # Windows"
|
||||
else
|
||||
echo ""
|
||||
echo "❌ PDF build failed - check errors above"
|
||||
echo ""
|
||||
echo "📝 Build artifacts in: _build/latex/"
|
||||
echo "Check _build/latex/tinytorch-course.log for detailed errors"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
66
book/build_pdf_simple.sh
Executable file
66
book/build_pdf_simple.sh
Executable file
@@ -0,0 +1,66 @@
|
||||
#!/bin/bash
|
||||
# Build PDF version of TinyTorch book (Simple HTML-to-PDF method)
|
||||
# This script builds PDF via HTML conversion - no LaTeX installation required
|
||||
|
||||
set -e # Exit on error
|
||||
|
||||
echo "🔥 Building TinyTorch PDF (Simple Method - No LaTeX Required)..."
|
||||
echo ""
|
||||
|
||||
# Check if we're in the book directory
|
||||
if [ ! -f "_config.yml" ]; then
|
||||
echo "❌ Error: Must run from book/ directory"
|
||||
echo "Usage: cd book && ./build_pdf_simple.sh"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check dependencies
|
||||
echo "📋 Checking dependencies..."
|
||||
if ! command -v jupyter-book &> /dev/null; then
|
||||
echo "❌ Error: jupyter-book not installed"
|
||||
echo "Install with: pip install jupyter-book pyppeteer"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check if pyppeteer is installed
|
||||
python3 -c "import pyppeteer" 2>/dev/null || {
|
||||
echo "❌ Error: pyppeteer not installed"
|
||||
echo "Install with: pip install pyppeteer"
|
||||
echo ""
|
||||
echo "Note: First run will download Chromium (~170MB)"
|
||||
exit 1
|
||||
}
|
||||
|
||||
echo "✅ Dependencies OK"
|
||||
echo ""
|
||||
|
||||
# Clean previous builds
|
||||
echo "🧹 Cleaning previous builds..."
|
||||
jupyter-book clean . --all || true
|
||||
echo ""
|
||||
|
||||
# Build PDF via HTML
|
||||
echo "📚 Building PDF from HTML (this may take a few minutes)..."
|
||||
echo "ℹ️ First run will download Chromium browser (~170MB)"
|
||||
jupyter-book build . --builder pdfhtml
|
||||
|
||||
# Check if build succeeded
|
||||
if [ -f "_build/pdf/book.pdf" ]; then
|
||||
# Copy to standard location with better name
|
||||
cp "_build/pdf/book.pdf" "_build/tinytorch-course.pdf"
|
||||
PDF_SIZE=$(du -h "_build/tinytorch-course.pdf" | cut -f1)
|
||||
echo ""
|
||||
echo "✅ PDF build complete!"
|
||||
echo "📄 Output: book/_build/tinytorch-course.pdf"
|
||||
echo "📊 Size: ${PDF_SIZE}"
|
||||
echo ""
|
||||
echo "To view the PDF:"
|
||||
echo " open _build/tinytorch-course.pdf # macOS"
|
||||
echo " xdg-open _build/tinytorch-course.pdf # Linux"
|
||||
echo " start _build/tinytorch-course.pdf # Windows"
|
||||
else
|
||||
echo ""
|
||||
echo "❌ PDF build failed - check errors above"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
Reference in New Issue
Block a user