From 361c586a7bd16d1697b6038d4188716f801b9fd5 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
Date: Fri, 10 Jul 2026 18:21:01 +0300
Subject: docs-infra: force latexmk through per-glyph/per-image LaTeX errors in
 PDF build
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pdflatex hard-errors on the Devanagari etymology text in
docs/introducing/history.md ("! LaTeX Error: Unicode character व
(U+0935) not set up for use with LaTeX") and separately cannot embed
several pre-existing .webp images (no BoundingBox) — both previously
undiscovered because the Devanagari error always halted the build
first. latexmk -f (force mode) + pdflatex -interaction=nonstopmode
makes the build tolerate both classes of per-glyph/per-image failure
and finish, matching how ReadTheDocs has always built this project's
PDF (verified against the live docs.vyos.io PDF: same Devanagari
glyphs blanked, same ~4 images embedded out of 2000+ pages).

latexmk exits non-zero in force mode even on a fully-produced PDF, so
the workflow step now verifies the artifact itself (exists, >2MB)
instead of relying on the command's exit code.

🤖 Generated by [robots](https://vyos.io)
---
 .github/workflows/docs-build.yml | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml
index fc9a2239..cff205e2 100644
--- a/.github/workflows/docs-build.yml
+++ b/.github/workflows/docs-build.yml
@@ -56,15 +56,36 @@ jobs:
           cache-to: type=gha,mode=max
 
       - name: Build HTML + PDF in in-workflow-built container
+        env:
+          # pdflatex hard-errors ("! LaTeX Error: Unicode character ... not
+          # set up for use with LaTeX") on the Devanagari etymology text in
+          # docs/introducing/history.md, and separately cannot embed some
+          # pre-existing .webp images (no BoundingBox). latexmk's force mode
+          # (-f) plus non-interactive pdflatex (-interaction=nonstopmode)
+          # makes it skip both classes of per-glyph/per-image failure and
+          # finish the document instead of halting — this is how ReadTheDocs
+          # has always built this project's PDF (verified against the live
+          # docs.vyos.io PDF: same Devanagari glyphs blanked, same ~4 images
+          # embedded out of 2000+ pages, rather than a failed build).
+          # latexmk still exits non-zero in force mode even when it produces
+          # a complete PDF, so success below is verified by checking the
+          # artifact itself, not the command's exit code.
+          LATEXMKOPTS: -f
+          LATEXOPTS: -interaction=nonstopmode
         run: |
           set -eu
           docker run --rm -v "$PWD:/src" -w /src \
             -e DOCS_VERSION_SLUG="${{ steps.matrix.outputs.slug }}" \
             -e DOCS_VERSION_BRANCH="${{ github.ref_name }}" \
+            -e LATEXMKOPTS \
+            -e LATEXOPTS \
             docs-build:local bash -c '
+              set -e
               cd docs && make html
               if [ "${{ inputs.skip_pdf }}" != "true" ]; then
-                make latexpdf || make latexpdf   # retry once (§14 LaTeX flakiness)
+                make latexpdf || true
+                pdf=$(find _build/latex -maxdepth 1 -name "*.pdf" -size +2M)
+                [ -n "$pdf" ] || { echo "no PDF >2MB produced in _build/latex — build genuinely failed"; exit 1; }
               fi'
 
       - name: Assemble artifact (nest under en/<slug>/, §7.1)
-- 
cgit v1.2.3