From ed4927172e6c55f2e9e7d3e6cfa24518fb9512ac Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 4 Jan 2026 04:30:17 +0000 Subject: [PATCH 1/3] Initial plan From 8759863be40ceb52afc352d001a13fc42ddcc068 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 4 Jan 2026 04:32:54 +0000 Subject: [PATCH 2/3] Initial plan for PDF build debugging enhancements Co-authored-by: jochym <5993422+jochym@users.noreply.github.com> --- .github/workflows/README.md | 70 ++++++++++++++++++++++++++++ .github/workflows/build-book-pdf.yml | 56 ++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 .github/workflows/README.md create mode 100644 .github/workflows/build-book-pdf.yml diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..7f53d3d --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,70 @@ +# 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 + - Artifacts are available for download from the Actions tab for 90 days + - Each workflow run creates a `book-pdf` artifact containing `main.pdf` + +### Accessing the PDF + +After a successful build: + +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 `book-pdf` artifact (will be a .zip file containing main.pdf) + +### 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. Check the workflow logs in the Actions tab for error messages +2. Common issues: + - Missing figures: Ensure all PDF/PNG files referenced in main.tex are in the book/ directory + - LaTeX syntax errors: Check the error log for line numbers + - Missing bibliography: The workflow expects inline bibliography (using `\begin{thebibliography}`) + +### Future enhancements + +Possible improvements to consider: +- Add automatic release creation for tagged versions +- Generate and upload build logs +- 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..d3df582 --- /dev/null +++ b/.github/workflows/build-book-pdf.yml @@ -0,0 +1,56 @@ +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 From 38ef822f7c999ac56b30bee5dc0640daa22e5763 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 4 Jan 2026 04:33:51 +0000 Subject: [PATCH 3/3] Add LaTeX build log artifact uploads for debugging Co-authored-by: jochym <5993422+jochym@users.noreply.github.com> --- .github/workflows/README.md | 33 ++++++++++++++++++++++++---- .github/workflows/build-book-pdf.yml | 15 +++++++++++++ 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 7f53d3d..713cfad 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -31,6 +31,28 @@ After a successful build: 3. Scroll down to the **Artifacts** section 4. Download the `book-pdf` artifact (will be a .zip file containing main.pdf) +### Accessing build logs for debugging + +For every workflow run (successful or failed), LaTeX build logs are automatically uploaded: + +1. Go to the **Actions** tab in the GitHub repository +2. Click on the workflow run you want to debug +3. Scroll down to the **Artifacts** section +4. Download the `latex-logs` artifact (will be a .zip file containing log files) +5. The artifact includes: + - `main.log` - Main LaTeX compilation log with detailed error messages + - `main.aux` - Auxiliary file with cross-references + - `main.out` - Hyperref output file + - `main.toc` - Table of contents data + - `main.bbl` - Bibliography file (if generated) + - `main.blg` - Bibliography log (if generated) + +The `main.log` file is especially useful for debugging compilation errors, as it contains: +- Line numbers where errors occurred +- Detailed error messages from LaTeX +- Warnings about missing packages, figures, or references +- Information about which files were processed + ### Manual triggering You can manually trigger a build: @@ -55,16 +77,19 @@ The workflow uses a full TeX Live distribution that includes all required packag ### Troubleshooting If the build fails: -1. Check the workflow logs in the Actions tab for error messages -2. Common issues: +1. Download the `latex-logs` artifact from the Actions tab (see "Accessing build logs" above) +2. Open `main.log` to see detailed error messages with line numbers +3. Check the workflow logs in the Actions tab for the summary output +4. Common issues: - Missing figures: Ensure all PDF/PNG files referenced in main.tex are in the book/ directory - - LaTeX syntax errors: Check the error log for line numbers + - LaTeX syntax errors: Check main.log for the specific line number and error message - Missing bibliography: The workflow expects inline bibliography (using `\begin{thebibliography}`) + - Package conflicts: Check main.log for package loading errors or conflicts ### Future enhancements Possible improvements to consider: - Add automatic release creation for tagged versions -- Generate and upload build logs - Cache TeX Live packages for faster builds - Add PDF validation/linting +- Generate HTML or other output formats alongside PDF diff --git a/.github/workflows/build-book-pdf.yml b/.github/workflows/build-book-pdf.yml index d3df582..9832704 100644 --- a/.github/workflows/build-book-pdf.yml +++ b/.github/workflows/build-book-pdf.yml @@ -54,3 +54,18 @@ jobs: 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-logs + path: | + book/*.log + book/*.aux + book/*.out + book/*.toc + book/*.blg + book/*.bbl + retention-days: 30 + if-no-files-found: warn