From 652e6e70428d9122cbae8a22dd129e6cffa650d4 Mon Sep 17 00:00:00 2001
From: Twisha Bansal <twishabansal07@gmail.com>
Date: Tue, 2 Jun 2026 13:29:51 +0530
Subject: [PATCH] ci(api-docs): add fork-safe PR preview workflow

---
 .github/workflows/api-docs-preview.yml | 95 ++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 .github/workflows/api-docs-preview.yml

diff --git a/.github/workflows/api-docs-preview.yml b/.github/workflows/api-docs-preview.yml
new file mode 100644
index 00000000..98cac9f4
--- /dev/null
+++ b/.github/workflows/api-docs-preview.yml
@@ -0,0 +1,95 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+name: "API Reference Preview"
+
+# Builds the docs for a PR and uploads them as a downloadable artifact.
+# Nothing is deployed and no secrets are used, so this runs safely on
+# pull requests from forks. Reviewers download the artifact and serve it
+# locally to preview the rendered site before merging.
+on:
+  pull_request:
+    paths:
+      - 'docs-site/**'
+      - 'scripts/generate-*.sh'
+      - '.github/workflows/api-docs-preview.yml'
+      - 'README.md'
+  # Allow previewing any change (e.g. package source) on demand.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: api-docs-preview-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version: '1.25.0'
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3
+        with:
+          hugo-version: '0.152.2'
+          extended: true
+
+      - name: Install PostCSS Dependencies
+        run: |
+          cd docs-site
+          npm install postcss postcss-cli autoprefixer
+
+      # Root-relative base URL keeps the artifact self-contained: links and
+      # assets resolve correctly when the folder is served from any host root.
+      - name: Build all packages and root page
+        run: |
+          chmod +x scripts/generate-api-docs.sh scripts/generate-root.sh
+          for PKG in core tbadk tbgenkit; do
+            ./scripts/generate-api-docs.sh "$PKG" dev "/"
+          done
+          ./scripts/generate-root.sh "/"
+
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: api-docs-preview
+          path: docs-site/public
+          retention-days: 7
+
+      - name: How to view
+        run: |
+          {
+            echo "### API Reference preview built"
+            echo ""
+            echo "Download the **api-docs-preview** artifact from this run, unzip it, then:"
+            echo ""
+            echo '```'
+            echo "cd api-docs-preview"
+            echo "python3 -m http.server 8080"
+            echo '```'
+            echo ""
+            echo "Open http://localhost:8080/ — package docs are at /core/dev/, /tbadk/dev/, /tbgenkit/dev/."
+          } >> "$GITHUB_STEP_SUMMARY"