diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..945d3e3 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,85 @@ +# GitHub Actions Workflows + +## Build Book PDF + +The `build-book-pdf.yml` workflow automatically builds the LaTeX book manuscript into a PDF. + +### How it works + +1. **Triggers**: The workflow runs when: + - Changes are pushed to the `book` branch in the `book/` directory + - Pull requests target the `book` branch with changes in `book/` directory + - Manually triggered from the Actions tab + +2. **Build process**: + - Checks out the repository + - Uses the `xu-cheng/latex-action@v3` to compile the LaTeX document + - Runs `latexmk` which automatically handles multiple pdflatex passes for cross-references + - Compiles `book/main.tex` into `book/main.pdf` + +3. **Output**: + - The generated PDF is uploaded as a GitHub Actions artifact (90-day retention) + - LaTeX build logs are uploaded as artifacts (30-day retention) for debugging + - Each workflow run creates: + - `book-pdf` artifact: Contains `main.pdf` (only on successful build) + - `latex-build-logs` artifact: Contains `.log`, `.aux`, and other build files (always uploaded) + +### Accessing the PDF and build logs + +After a workflow run: + +1. Go to the **Actions** tab in the GitHub repository +2. Click on the workflow run you're interested in +3. Scroll down to the **Artifacts** section +4. Download the artifacts: + - **book-pdf**: The compiled PDF (available only if build succeeded) + - **latex-build-logs**: LaTeX log files for debugging (always available) + +Both artifacts are .zip files that need to be extracted after download. + +### Manual triggering + +You can manually trigger a build: + +1. Go to **Actions** tab +2. Select **Build Book PDF** workflow +3. Click **Run workflow** button +4. Select the `book` branch +5. Click **Run workflow** + +### LaTeX packages + +The workflow uses a full TeX Live distribution that includes all required packages: +- graphicx, epsfig (for figures) +- amsmath (for mathematical notation) +- hyperref (for hyperlinks and cross-references) +- geometry (for page layout) +- longtable, dcolumn (for tables) +- bm (for bold math) +- And many more standard packages + +### Troubleshooting + +If the build fails: + +1. **Download the build logs**: + - Go to the Actions tab and find the failed workflow run + - Scroll to the **Artifacts** section + - Download the `latex-build-logs` artifact + - Extract the .zip file and open `main.log` to see detailed error messages + +2. **Check the workflow logs**: + - Click on the failed job in the Actions tab + - Review the "Compile LaTeX document" step for immediate error output + +3. **Common issues**: + - Missing figures: Ensure all PDF/PNG files referenced in main.tex are in the book/ directory + - LaTeX syntax errors: Check the .log file for line numbers and error context + - Missing bibliography: The workflow expects inline bibliography (using `\begin{thebibliography}`) + +### Future enhancements + +Possible improvements to consider: +- Add automatic release creation for tagged versions +- Cache TeX Live packages for faster builds +- Add PDF validation/linting diff --git a/.github/workflows/build-book-pdf.yml b/.github/workflows/build-book-pdf.yml new file mode 100644 index 0000000..629e5c1 --- /dev/null +++ b/.github/workflows/build-book-pdf.yml @@ -0,0 +1,72 @@ +name: Build Book PDF + +# Trigger the workflow on pushes and pull requests to the book branch +on: + push: + branches: + - book + paths: + - 'book/**' + pull_request: + branches: + - book + paths: + - 'book/**' + # Allow manual triggering from Actions tab + workflow_dispatch: + +jobs: + build-pdf: + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Compile LaTeX document + uses: xu-cheng/latex-action@v3 + with: + root_file: main.tex + working_directory: book + # Use latexmk for automatic handling of multiple passes + args: -pdf -file-line-error -interaction=nonstopmode + latexmk_use_lualatex: false + latexmk_use_xelatex: false + latexmk_shell_escape: false + + - name: Check PDF was created + run: | + if [ -f book/main.pdf ]; then + echo "✓ PDF successfully created" + ls -lh book/main.pdf + else + echo "✗ PDF was not created" + exit 1 + fi + + - name: Upload PDF artifact + if: success() + uses: actions/upload-artifact@v4 + with: + name: book-pdf + path: book/main.pdf + retention-days: 90 + + - name: Upload LaTeX build logs + if: always() + uses: actions/upload-artifact@v4 + with: + name: latex-build-logs + path: | + book/*.log + book/*.aux + book/*.out + book/*.blg + book/*.bbl + book/*.fls + book/*.fdb_latexmk + retention-days: 30 + if-no-files-found: warn