feat(FR-2719): build per-language User Guide PDFs in CI release workflow

- Add a new build_docs job to .github/workflows/package.yml that runs
  independently of build_web in parallel with the desktop jobs, so adding
  PDFs does not extend the overall release wall-clock (the critical path
  is still the ~10 min build_mac job).
- The job caches Playwright browsers, installs only Chromium, best-effort
  installs language-specific single-file CJK and Thai fonts referenced by
  pdf-renderer's DEFAULT_CJK_FONT_CANDIDATES, runs pdf:all, stages PDFs
  into ./app/, uploads them via upload-release.js (gated on dry_run), and
  always retains them as a workflow artifact for inspection.
- Allow .pdf in upload-release.js's asset extension filter alongside
  .dmg and .zip.
- In the toolkit, share one Chromium instance across languages and fan
  out per-language renders with a configurable concurrency (default 2,
  override via BAI_DOCS_PDF_CONCURRENCY). renderPdf accepts an optional
  injected Browser so the caller owns lifecycle.
- Isolate per-language failures in generate-pdf.ts: the script logs each
  failure, continues with remaining languages, and exits non-zero only
  if every requested language failed. Combined with continue-on-error
  on the job, partial CJK font issues no longer block English uploads.

Author: yomybaby

.github/workflows/package.yml

@@ -1,16 +1,20 @@
 # Build and release workflow for Backend.AI Desktop and WebUI bundle.
 #
-# Architecture: 3 parallel jobs after a shared web build step.
+# Architecture: 4 parallel jobs (build_docs is fully independent, the others
+# share a web build step).
 #
 #   build_web (ubuntu) ──┬──> build_mac (macos)    → DMG x64/arm64 + local proxy
 #                        ├──> build_desktop (ubuntu) → Win/Linux ZIP x64/arm64 + local proxy
 #                        └──> upload web bundle
+#   build_docs (ubuntu, independent)               → User Guide PDFs (en/ko/ja/th)
 #
 # Key optimizations over the previous single-job approach:
-#   1. Parallel jobs: macOS + win/linux builds run concurrently (~10 min saved)
+#   1. Parallel jobs: macOS + win/linux + docs builds run concurrently (~10 min saved)
 #   2. No double React build: publicPath patching replaces full rebuild (~5 min saved)
 #   3. Parallel local proxy compilation within each job (~3 min saved)
 #   4. Optimized ZIP compression level (-6 vs -9, marginal size diff, ~1 min saved)
+#   5. PDF generation reuses one Chromium instance and renders languages in
+#      parallel; Playwright browsers are cached across runs.
 
 name: Build and Release Packages
 on:
@@ -204,3 +208,100 @@ jobs:
         run: node upload-release.js app
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # ──────────────────────────────────────────────────────────────────────
+  # Job 4: Build per-language User Guide PDFs (ubuntu, target ~5 min)
+  #
+  # Independent of the web/desktop jobs — only needs the docs sources under
+  # `packages/backend.ai-webui-docs/src/`. Runs in parallel with build_mac
+  # and build_desktop, so a healthy run does not extend the overall wall
+  # clock (mac is the current critical path at ~10 min).
+  #
+  # `continue-on-error: true` means a PDF failure logs warnings but does
+  # NOT block the release. Tighten this once the pipeline has soaked.
+  # ──────────────────────────────────────────────────────────────────────
+  build_docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v5
+
+      - uses: pnpm/action-setup@v5
+        name: Install pnpm
+        with:
+          version: latest
+          run_install: false
+
+      - name: Install Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+
+      - name: Install Dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      # Cache the Playwright browser binaries (~150 MB Chromium download).
+      # The lockfile hash keys the cache so a Playwright version bump
+      # naturally invalidates the cache without manual intervention.
+      - name: Cache Playwright browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Install Playwright Chromium
+        run: pnpm --filter backend.ai-webui-docs exec playwright install --with-deps chromium
+
+      # Install single-face CJK + Thai fonts. Ubuntu's `fonts-noto-cjk`
+      # ships only a TTC bundle that pdf-lib/fontkit cannot embed, so we
+      # use language-specific single-file packages whose paths are listed
+      # in DEFAULT_CJK_FONT_CANDIDATES (pdf-renderer.ts):
+      #   - fonts-nanum     → /usr/share/fonts/truetype/nanum/NanumBarunGothic.ttf  (ko)
+      #   - fonts-takao-gothic → /usr/share/fonts/truetype/takao-gothic/TakaoGothic.ttf (ja)
+      #   - fonts-thai-tlwg → /usr/share/fonts/truetype/tlwg/Loma.ttf  (th)
+      # Languages whose font is missing will be reported as a failure by
+      # generate-pdf.ts but will not abort the other language renders.
+      - name: Install CJK + Thai fonts (best effort)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            fonts-nanum fonts-takao-gothic fonts-thai-tlwg || true
+
+      # generate-pdf.ts continues past per-language failures and exits
+      # non-zero only if *every* requested language failed. Combined with
+      # `continue-on-error: true` on the job, a partial PDF run still
+      # uploads the languages that succeeded.
+      - name: Build PDFs (en/ko/ja/th)
+        run: pnpm --filter backend.ai-webui-docs run pdf:all
+
+      - name: Stage PDFs for upload
+        run: |
+          mkdir -p ./app
+          if compgen -G "packages/backend.ai-webui-docs/dist/*.pdf" > /dev/null; then
+            cp packages/backend.ai-webui-docs/dist/*.pdf ./app/
+            ls -lh ./app/*.pdf
+          else
+            echo "::warning::No PDFs were produced; nothing to upload."
+          fi
+
+      - name: Upload PDF release assets
+        if: inputs.dry_run != true
+        run: node upload-release.js app
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Always retain the built PDFs as a workflow artifact for inspection
+      # (handy during dry runs and when debugging the release path).
+      - name: Upload PDFs as workflow artifact
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: webui-docs-pdfs
+          path: packages/backend.ai-webui-docs/dist/*.pdf
+          if-no-files-found: warn
+          retention-days: 14

packages/backend.ai-docs-toolkit/src/generate-pdf.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { parse as parseYaml } from 'yaml';
+import { chromium } from 'playwright';
 import { processMarkdownFiles } from './markdown-processor.js';
 import { buildFullDocument } from './html-builder.js';
 import { renderPdf } from './pdf-renderer.js';
@@ -20,6 +21,12 @@ export interface GeneratePdfOptions {
   theme: string;
   chapters?: string[];
   note?: string;
+  /**
+   * Maximum number of languages to render concurrently.
+   * Defaults to 2 (safe for GitHub-hosted ubuntu runners with 2 vCPU).
+   * Override via the `BAI_DOCS_PDF_CONCURRENCY` env var.
+   */
+  concurrency?: number;
 }
 
 function parseArgs(argv: string[]): GeneratePdfOptions {
@@ -85,22 +92,37 @@ export async function generatePdf(
     }
   }
 
+  const envConcurrency = Number.parseInt(
+    process.env.BAI_DOCS_PDF_CONCURRENCY ?? '',
+    10,
+  );
+  const concurrency = Math.max(
+    1,
+    args.concurrency ?? (Number.isFinite(envConcurrency) ? envConcurrency : 2),
+  );
+
   const productName = config.productName;
   console.log(`${productName} PDF Generator`);
   console.log(`Title: ${title}`);
   console.log(`Version: ${version}`);
   console.log(`Theme: ${theme.name}`);
   console.log(`Languages: ${languages.join(', ')}`);
+  console.log(`Concurrency: ${concurrency}`);
   console.log('');
 
-  for (const lang of languages) {
+  // Launch a single Chromium instance shared across all language renders.
+  // Each renderPdf call opens its own page on this browser, which avoids
+  // paying the launch cost (~1–2s) per language.
+  const sharedBrowser = await chromium.launch();
+
+  const renderOne = async (lang: string): Promise<void> => {
     const startTime = Date.now();
     console.log(`[${lang}] Generating PDF...`);
 
     let navigation = bookConfig.navigation[lang];
     if (!navigation) {
       console.warn(`[${lang}] No navigation found, skipping`);
-      continue;
+      return;
     }
 
     // Filter chapters if --chapters option is specified
@@ -129,7 +151,7 @@ export async function generatePdf(
           `[${lang}] Chapter identifiers can be a full path (e.g. overview/overview.md), directory name, or filename.`,
         );
         console.error(`[${lang}] Available chapters: ${available}`);
-        process.exit(1);
+        throw new Error(`No chapters matched filter for "${lang}"`);
       }
       navigation = filtered;
       console.log(
@@ -173,6 +195,7 @@ export async function generatePdf(
       lang,
       theme,
       config,
+      browser: sharedBrowser,
     });
 
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
@@ -181,7 +204,55 @@ export async function generatePdf(
       `[${lang}] Done: ${outputPath} (${fileSize} MB, ${elapsed}s)`,
     );
     console.log('');
+  };
+
+  // Track per-language outcome so a single language failure (e.g. missing
+  // CJK font on a runner) does not kill renders that have already started
+  // or are still queued. The script exits non-zero only if *every*
+  // requested language failed.
+  const failures: Array<{ lang: string; error: Error }> = [];
+
+  try {
+    // Concurrency-limited fan-out: process up to `concurrency` languages at
+    // a time. Each worker pulls the next language from a shared cursor.
+    const queue = [...languages];
+    const workers: Promise<void>[] = [];
+    const workerCount = Math.min(concurrency, queue.length);
+    for (let i = 0; i < workerCount; i++) {
+      workers.push(
+        (async () => {
+          while (queue.length > 0) {
+            const lang = queue.shift();
+            if (!lang) break;
+            try {
+              await renderOne(lang);
+            } catch (err) {
+              const error = err instanceof Error ? err : new Error(String(err));
+              console.error(`[${lang}] FAILED: ${error.message}`);
+              failures.push({ lang, error });
+            }
+          }
+        })(),
+      );
+    }
+    await Promise.all(workers);
+  } finally {
+    await sharedBrowser.close();
   }
 
-  console.log('PDF generation complete!');
+  if (failures.length > 0) {
+    console.log('');
+    console.log(`PDF generation finished with ${failures.length}/${languages.length} failures:`);
+    for (const { lang, error } of failures) {
+      console.log(`  - [${lang}] ${error.message}`);
+    }
+    if (failures.length === languages.length) {
+      throw new Error('All requested languages failed to build');
+    }
+    console.log(
+      `Continuing because ${languages.length - failures.length} language(s) succeeded.`,
+    );
+  } else {
+    console.log('PDF generation complete!');
+  }
 }

packages/backend.ai-docs-toolkit/src/pdf-renderer.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { pathToFileURL } from 'url';
-import { chromium } from 'playwright';
+import { chromium, type Browser } from 'playwright';
 import { PDFDocument, PDFName, PDFArray, PDFDict, PDFRef, rgb, StandardFonts } from 'pdf-lib';
 import fontkit from '@pdf-lib/fontkit';
 import type { PdfTheme } from './theme.js';
@@ -61,6 +61,13 @@ export interface RenderOptions {
   lang: string;
   theme?: PdfTheme;
   config?: ResolvedDocConfig;
+  /**
+   * Optional shared Chromium instance. When provided, renderPdf reuses it
+   * (via newContext/newPage) and the caller owns its lifecycle. This avoids
+   * paying the per-call launch cost when generating multiple PDFs in one run
+   * (e.g. one PDF per language during release builds).
+   */
+  browser?: Browser;
 }
 
 interface ChapterInfo {
@@ -386,12 +393,14 @@ export async function renderPdf(options: RenderOptions): Promise<void> {
   const tmpHtmlPath = path.join(tmpDir, 'document.html');
   fs.writeFileSync(tmpHtmlPath, options.html, 'utf-8');
 
-  const browser = await chromium.launch();
+  const ownsBrowser = !options.browser;
+  const browser = options.browser ?? (await chromium.launch());
   let pdfBuffer: Buffer;
   let chapterInfoList: ChapterInfo[] = [];
   let sectionList: SectionInfo[] = [];
+  let page: Awaited<ReturnType<Browser['newPage']>> | undefined;
   try {
-    const page = await browser.newPage({
+    page = await browser.newPage({
       viewport: { width: PRINT_WIDTH_PX, height: 800 },
     });
 
@@ -479,7 +488,12 @@ export async function renderPdf(options: RenderOptions): Promise<void> {
     console.log('  Rendering final PDF...');
     pdfBuffer = await page.pdf(PDF_OPTIONS);
   } finally {
-    await browser.close();
+    if (page) {
+      await page.close().catch(() => {});
+    }
+    if (ownsBrowser) {
+      await browser.close();
+    }
     fs.rmSync(tmpDir, { recursive: true, force: true });
   }
 

upload-release.js

@@ -51,15 +51,15 @@ const main = async () => {
         process.exit(1)
     }
     const folder = process.argv[2]
-    let DMGs = []
+    let assets = []
     try {
-        DMGs = (await fs.promises.readdir(folder)).filter((s) => !s.startsWith('.') && (s.endsWith('.dmg') || s.endsWith('.zip')))
+        assets = (await fs.promises.readdir(folder)).filter((s) => !s.startsWith('.') && (s.endsWith('.dmg') || s.endsWith('.zip') || s.endsWith('.pdf')))
     } catch (e) {
         console.error(e.message)
         process.exit(1)
     }
 
-    console.log(`found ${DMGs.length} DMG(s): ${DMGs}`)
+    console.log(`found ${assets.length} asset(s): ${assets}`)
 
     const tag = process.env.RELEASE_TAG || (await getLatestTag())
     const releaseId = await getReleaseIdFromTag(tag)
@@ -94,8 +94,8 @@ const main = async () => {
     }
 
     // Process uploads in batches to avoid overwhelming the API
-    for (let i = 0; i < DMGs.length; i += CONCURRENCY) {
-        const batch = DMGs.slice(i, i + CONCURRENCY)
+    for (let i = 0; i < assets.length; i += CONCURRENCY) {
+        const batch = assets.slice(i, i + CONCURRENCY)
         await Promise.all(batch.map(uploadFile))
     }
 }