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

yomybaby · yomybaby · commit dfd734911552 · 2026-04-26T03:23:59.000Z
resolves #NNN (FR-MMM)
&lt;!-- replace NNN, MMM with the GitHub issue number and the corresponding Jira issue number. --&gt;

&lt;!--
Please precisely, concisely, and concretely describe what this PR changes, the rationale behind codes,
and how it affects the users and other developers.
--&gt;

**Checklist:** (if applicable)

- [ ] Documentation
- [ ] Minium required manager version
- [ ] Specific setting for review (eg., KB link, endpoint or how to setup)
- [ ] Minimum requirements to check during review
- [ ] Test case(s) to demonstrate the difference of before/after
diff --git a/.github/workflows/package.yml b/.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,123 @@ 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).
+  #
+  # Failure handling is scoped to the PDF build step itself (not the whole
+  # job), so partial per-language failures degrade gracefully but a full
+  # generator failure (all languages failed → generate-pdf.ts exits non-
+  # zero) still fails the job. This prevents shipping a release with zero
+  # PDF assets going unnoticed.
+  # ──────────────────────────────────────────────────────────────────────
+  build_docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    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
+
+      # backend.ai-docs-toolkit ships its `docs-toolkit` CLI as the package
+      # bin, but it lives at dist/cli.js which only exists after `tsc` runs.
+      # On a fresh `pnpm install` the dist directory is empty, so pnpm
+      # cannot create the .bin/docs-toolkit symlink and later `pdf:all`
+      # fails with `spawn ENOENT`. Building the toolkit and re-running
+      # install populates dist/ and lets pnpm wire the bin link.
+      - name: Build docs-toolkit and link CLI
+        run: |
+          pnpm --filter backend.ai-docs-toolkit run build
+          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
+
+      # PDF rendering uses two distinct font paths that need different fonts:
+      #
+      # 1. Body text — rendered by Chromium from HTML. Resolves the CSS
+      #    font-family (see styles.ts) via fontconfig, so it understands
+      #    .ttc collections. `fonts-noto-cjk` provides "Noto Sans CJK KR/JP/TC"
+      #    which the CSS lists as the canonical CJK body font.
+      #
+      # 2. Header/footer — stamped post-render by pdf-lib, which cannot embed
+      #    .ttc collections. So we additionally install language-specific
+      #    single-face 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/opentype/tlwg/Loma.otf | Garuda.ttf  (th)
+      #
+      # Languages whose pdf-lib 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-noto-cjk \
+            fonts-nanum fonts-takao-gothic fonts-thai-tlwg || true
+          fc-cache -f || 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
diff --git a/packages/backend.ai-docs-toolkit/src/generate-pdf.ts b/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,40 @@ export async function generatePdf(
     }
   }
 
+  const envConcurrency = Number.parseInt(
+    process.env.BAI_DOCS_PDF_CONCURRENCY ?? '',
+    10,
+  );
+  const optionConcurrency = Number.isFinite(args.concurrency)
+    ? args.concurrency
+    : undefined;
+  const concurrency = Math.max(
+    1,
+    optionConcurrency ?? (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 +154,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 +198,7 @@ export async function generatePdf(
       lang,
       theme,
       config,
+      browser: sharedBrowser,
     });
 
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
@@ -181,7 +207,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!');
+  }
 }
diff --git a/packages/backend.ai-docs-toolkit/src/pdf-renderer.ts b/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';
@@ -19,10 +19,17 @@ const DEFAULT_CJK_FONT_CANDIDATES = [
   path.join(os.homedir(), 'Library/Fonts/NanumBarunGothic.ttf'),
   path.join(os.homedir(), 'Library/Fonts/NanumSquareRegular.ttf'),
   '/System/Library/Fonts/Supplemental/Arial Unicode.ttf',
-  // Linux common paths
+  // Linux common paths — Korean
   '/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc',
   '/usr/share/fonts/truetype/noto/NotoSansKR-Regular.ttf',
   '/usr/share/fonts/truetype/nanum/NanumBarunGothic.ttf',
+  // Linux common paths — Japanese (fonts-takao-gothic on Debian/Ubuntu)
+  '/usr/share/fonts/truetype/takao-gothic/TakaoGothic.ttf',
+  '/usr/share/fonts/truetype/takao-mincho/TakaoMincho.ttf',
+  // Linux common paths — Thai (fonts-thai-tlwg on Debian/Ubuntu)
+  '/usr/share/fonts/truetype/tlwg/Loma.ttf',
+  '/usr/share/fonts/opentype/tlwg/Loma.otf',
+  '/usr/share/fonts/truetype/tlwg/Garuda.ttf',
 ];
 
 type EmbeddedFont = Awaited<ReturnType<PDFDocument['embedFont']>>;
@@ -61,6 +68,13 @@ export interface RenderOptions {
   lang: string;
   theme?: PdfTheme;
   config?: ResolvedDocConfig;
+  /**
+   * Optional shared Chromium instance. When provided, renderPdf reuses it
+   * by opening a new page on the existing browser, 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 {
@@ -382,16 +396,23 @@ export async function renderPdf(options: RenderOptions): Promise<void> {
 
   fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
 
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bai-docs-'));
-  const tmpHtmlPath = path.join(tmpDir, 'document.html');
-  fs.writeFileSync(tmpHtmlPath, options.html, 'utf-8');
+  const ownsBrowser = !options.browser;
+  const browser = options.browser ?? (await chromium.launch());
 
-  const browser = await chromium.launch();
+  // tmpDir is created after the browser is ready so a chromium.launch()
+  // failure cannot leave an orphaned temp directory behind. Use an outer
+  // try/finally so a failure between mkdtempSync and the inner try also
+  // cleans up the browser when we own it.
+  let tmpDir: string | undefined;
   let pdfBuffer: Buffer;
   let chapterInfoList: ChapterInfo[] = [];
   let sectionList: SectionInfo[] = [];
+  let page: Awaited<ReturnType<Browser['newPage']>> | undefined;
   try {
-    const page = await browser.newPage({
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bai-docs-'));
+    const tmpHtmlPath = path.join(tmpDir, 'document.html');
+    fs.writeFileSync(tmpHtmlPath, options.html, 'utf-8');
+    page = await browser.newPage({
       viewport: { width: PRINT_WIDTH_PX, height: 800 },
     });
 
@@ -479,8 +500,15 @@ export async function renderPdf(options: RenderOptions): Promise<void> {
     console.log('  Rendering final PDF...');
     pdfBuffer = await page.pdf(PDF_OPTIONS);
   } finally {
-    await browser.close();
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    if (page) {
+      await page.close().catch(() => {});
+    }
+    if (ownsBrowser) {
+      await browser.close();
+    }
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
   }
 
   // ── Post-processing ──────────────────────────────────────────
diff --git a/packages/backend.ai-docs-toolkit/src/styles-web.ts b/packages/backend.ai-docs-toolkit/src/styles-web.ts
@@ -50,7 +50,11 @@ export function generateWebStyles(lang?: string): string {
   --ifm-color-emphasis-1000: #000;
 
   --ifm-font-family-base: system-ui, -apple-system, "Segoe UI", Roboto,
-    Ubuntu, Cantarell, "Noto Sans", "Noto Sans KR", "Noto Sans JP", "Noto Sans Thai",
+    Ubuntu, Cantarell, "Noto Sans",
+    "Noto Sans KR", "Noto Sans CJK KR",
+    "Noto Sans JP", "Noto Sans CJK JP",
+    "Noto Sans TC", "Noto Sans CJK TC",
+    "Noto Sans Thai",
     sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   --ifm-font-family-monospace: "SFMono-Regular", Menlo, Consolas, "Liberation Mono", "Courier New", monospace;
 
diff --git a/packages/backend.ai-docs-toolkit/src/styles.ts b/packages/backend.ai-docs-toolkit/src/styles.ts
diff --git a/upload-release.js b/upload-release.js
