revise README #3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: build and release PDFs | |
| # Pull requests build only, so a merge is never the first time this workflow runs | |
| # against a change. Pushes to main build and publish. | |
| on: | |
| push: | |
| branches: [main] | |
| pull_request: | |
| branches: [main] | |
| workflow_dispatch: | |
| # The release step creates tags and releases. | |
| permissions: | |
| contents: write | |
| # Per-ref, so a PR build and a main build never cancel each other. Within one ref, | |
| # superseding runs win: two merges in quick succession would otherwise race to move | |
| # the `latest` tag, and the older build is the one worth dropping. | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| pdf: | |
| runs-on: ubuntu-latest | |
| env: | |
| PANDOC_VERSION: "3.10.1" | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: Install pandoc, XeLaTeX and fonts | |
| run: | | |
| # apt's pandoc is too old for --syntax-highlighting, so take the upstream deb. | |
| curl -fsSLO "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-1-amd64.deb" | |
| sudo apt-get update | |
| sudo apt-get install -y \ | |
| "./pandoc-${PANDOC_VERSION}-1-amd64.deb" \ | |
| texlive-xetex texlive-latex-recommended texlive-latex-extra \ | |
| fonts-texgyre fonts-texgyre-math fonts-dejavu-mono | |
| rm -f "pandoc-${PANDOC_VERSION}-1-amd64.deb" | |
| pandoc --version | head -1 | |
| xelatex --version | head -1 | |
| # fontspec resolves the -V font names through fontconfig. If one is missing it | |
| # falls back silently in some cases, so check here rather than ship a PDF set in | |
| # the wrong typeface. Names must match tools/build.sh and tools/header.tex. | |
| - name: Verify fonts are visible to fontconfig | |
| run: | | |
| fc-cache -f > /dev/null | |
| for font in "TeX Gyre Pagella" "TeX Gyre Heros" "DejaVu Sans Mono" "TeX Gyre Pagella Math"; do | |
| if fc-list -f '%{family[0]}\n' | grep -qxF "$font"; then | |
| echo "ok: $font" | |
| else | |
| echo "::error::font not installed: $font" | |
| exit 1 | |
| fi | |
| done | |
| - name: Build PDFs | |
| run: | | |
| mkdir -p build | |
| for doc in perception-guide math-primer notation; do | |
| echo "::group::$doc.md" | |
| tools/build.sh "$doc.md" "build/$doc.pdf" | |
| echo "::endgroup::" | |
| done | |
| ls -lh build | |
| # check.py is a heuristic linter and always exits 0 by design, so this is a | |
| # report on the job summary, not a gate on the release. | |
| - name: Linter report | |
| run: python3 tools/check.py >> "$GITHUB_STEP_SUMMARY" | |
| # On a PR the PDFs are the check: download them from the run's Artifacts section. | |
| # Pushes to main skip this — the release below is the durable copy. | |
| - name: Upload PDFs as a build artifact | |
| if: github.event_name == 'pull_request' | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: pdfs | |
| path: build/*.pdf | |
| if-no-files-found: error | |
| retention-days: 14 | |
| - name: Publish rolling "latest" release | |
| if: github.event_name != 'pull_request' | |
| env: | |
| GH_TOKEN: ${{ github.token }} | |
| run: | | |
| { | |
| echo "PDFs built from \`${GITHUB_SHA:0:7}\` on $(date -u '+%Y-%m-%d %H:%M UTC')." | |
| echo | |
| echo "Latest commit: $(git log -1 --pretty='%s')" | |
| } > "$RUNNER_TEMP/notes.md" | |
| # Delete and recreate so the `latest` tag moves to this commit. The release | |
| # may not exist on the first run, hence the `|| true`. | |
| gh release delete latest --yes --cleanup-tag || true | |
| gh release create latest \ | |
| --target "$GITHUB_SHA" \ | |
| --title "Perception Handbook — latest build" \ | |
| --notes-file "$RUNNER_TEMP/notes.md" \ | |
| --latest \ | |
| build/perception-guide.pdf \ | |
| build/math-primer.pdf \ | |
| build/notation.pdf |