diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..713cfad --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,95 @@ +# 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) + +### 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: + +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 `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 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 +- 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 new file mode 100644 index 0000000..9832704 --- /dev/null +++ b/.github/workflows/build-book-pdf.yml @@ -0,0 +1,71 @@ +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-logs + path: | + book/*.log + book/*.aux + book/*.out + book/*.toc + book/*.blg + book/*.bbl + retention-days: 30 + if-no-files-found: warn