Merge pull request #2 from omerssid/dev-rewrite-math-and-core-sections

Dev rewrite math and core perception sections

Author: omerssid

.github/workflows/build-and-release.yml

@@ -0,0 +1,107 @@
+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

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+
+build/