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:
Vijay Janapa Reddi
2025-11-09 14:51:48 -05:00
parent d93511d36b
commit 6788fca024
4 changed files with 293 additions and 0 deletions

100
.github/workflows/build-pdf.yml vendored Normal file
View 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
View 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
View 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
View 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