From 942bc481a72382d1afe5c993b0537470f9a07833 Mon Sep 17 00:00:00 2001
From: h1065153539-create <h1065153539-create@users.noreply.github.com>
Date: Fri, 26 Jun 2026 23:45:39 +0800
Subject: [PATCH] ci: add per-package rustdoc job

---
 .github/workflows/rustdoc.yml | 52 +++++++++++++++++++++++++++++++++++
 docs/RUSTDOC.md               | 14 ++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 .github/workflows/rustdoc.yml

diff --git a/.github/workflows/rustdoc.yml b/.github/workflows/rustdoc.yml
new file mode 100644
index 00000000..d8a85476
--- /dev/null
+++ b/.github/workflows/rustdoc.yml
@@ -0,0 +1,52 @@
+name: Rustdoc
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - ".github/workflows/rustdoc.yml"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "src/**"
+      - "quicklendx-contracts/**"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - ".github/workflows/rustdoc.yml"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "src/**"
+      - "quicklendx-contracts/**"
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  cargo-doc:
+    name: cargo doc (${{ matrix.package.name }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: root contract crate
+            working-directory: .
+          - name: quicklendx-contracts
+            working-directory: quicklendx-contracts
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          source "$HOME/.cargo/env"
+          rustup show
+
+      - name: Generate package rustdoc
+        working-directory: ${{ matrix.package.working-directory }}
+        run: |
+          source "$HOME/.cargo/env"
+          cargo doc --no-deps --locked
diff --git a/docs/RUSTDOC.md b/docs/RUSTDOC.md
index 1ea1eec6..65d1e85a 100644
--- a/docs/RUSTDOC.md
+++ b/docs/RUSTDOC.md
@@ -98,6 +98,20 @@ The published URL is updated automatically on every tag push — no manual step
 
 If the published URL returns a 404, the most likely cause is that no tag has been pushed yet for the current development cycle. Generate the docs locally using the command above, or check the repository's Actions tab to confirm the publish workflow ran successfully.
 
+## Pull request validation
+
+Every push to `main` and every pull request that touches contract sources,
+Cargo metadata, or the rustdoc workflow runs `.github/workflows/rustdoc.yml`.
+That workflow checks each contract package independently:
+
+| Package | Working directory | Command |
+|---|---|---|
+| Root contract crate | `.` | `cargo doc --no-deps --locked` |
+| Smart contract package | `quicklendx-contracts/` | `cargo doc --no-deps --locked` |
+
+The matrix keeps rustdoc failures scoped to the package that introduced them
+and prevents a healthy package from hiding a broken API surface in another one.
+
 ---
 
 ## Related documentation