From 105ed3fd3c4a6a162cc138db1a04afc460c75084 Mon Sep 17 00:00:00 2001
From: jiangjianfeng <jiangjianfeng.jjf@antgroup.com>
Date: Thu, 26 Jun 2025 09:33:16 +0000
Subject: [PATCH] Add workflows to publish API documentation to self-hosted
 website

---
 .github/workflows/publish_api_docs.yml        | 48 +++++++++++++++++++
 ...upload_api_docs.sh => publish_api_docs.sh} | 43 ++++++++++++-----
 2 files changed, 79 insertions(+), 12 deletions(-)
 create mode 100644 .github/workflows/publish_api_docs.yml
 rename tools/github_workflows/{build_and_upload_api_docs.sh => publish_api_docs.sh} (79%)

diff --git a/.github/workflows/publish_api_docs.yml b/.github/workflows/publish_api_docs.yml
new file mode 100644
index 000000000..7259eaf19
--- /dev/null
+++ b/.github/workflows/publish_api_docs.yml
@@ -0,0 +1,48 @@
+name: Publish API Docs
+
+on:
+  # Manally run
+  workflow_dispatch:
+  # Pull request events for checking API docs
+  pull_request:
+  # Scheduled events for nightly API docs
+  schedule:
+    # UTC 00:00 everyday
+    - cron: "0 0 * * *"
+  # Events for API docs of new release
+  push:
+    branches:
+      - main
+    paths:
+      - VERSION
+  
+jobs: 
+  check_api_docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    container: asterinas/asterinas:0.15.2-20250613
+
+    steps: 
+      - uses: actions/checkout@v4
+
+      - name: Check API docs
+        if: github.event_name == 'pull_request'
+        run: ./tools/github_workflows/publish_api_docs.sh --dry-run
+
+      - name: Build & Upload Nightly API Docs
+        if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+        env:
+          API_DOCS_NIGHTLY_PUBLISH_KEY: ${{ secrets.API_DOCS_NIGHTLY_PUBLISH_KEY }}
+        run: |
+          KEY_FILE=./api_docs_nightly_publish_key
+          echo "$API_DOCS_NIGHTLY_PUBLISH_KEY\n" > ${KEY_FILE}
+          ./tools/github_workflows/publish_api_docs.sh nightly ${KEY_FILE} 
+
+      - name: Build & Upload Release API Docs
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        env:
+          API_DOCS_PUBLISH_KEY: ${{ secrets.API_DOCS_PUBLISH_KEY }}
+        run: |
+          KEY_FILE=./api_docs_publish_key
+          echo "$API_DOCS_PUBLISH_KEY\n" > ${KEY_FILE}
+          ./tools/github_workflows/publish_api_docs.sh release ${KEY_FILE} 
diff --git a/tools/github_workflows/build_and_upload_api_docs.sh b/tools/github_workflows/publish_api_docs.sh
similarity index 79%
rename from tools/github_workflows/build_and_upload_api_docs.sh
rename to tools/github_workflows/publish_api_docs.sh
index 0059876f6..ed5ca79b0 100755
--- a/tools/github_workflows/build_and_upload_api_docs.sh
+++ b/tools/github_workflows/publish_api_docs.sh
@@ -9,20 +9,24 @@ set -e
 
 # Print help message
 print_help() {
-    echo "Usage: $0 [nightly | release] <key_file>"
+    echo "Usage: $0 [--dry-run | --nightly <key_file> | --release <key_file>]"
     echo ""
     echo "Options:"
-    echo "    nightly:  Update nightly API documentations"
-    echo "    release:  Update API documentations of a new version"
-    echo "key_file: The path to the file that stores the SSH key"
+    echo "    --dry-run    Build documentation without uploading."
+    echo "    nightly      Build and upload nightly API documentation."
+    echo "    release      Build and upload API documentation for a new version."
+    echo "    key_file     Path to the file that stores the SSH key. Required if documentation needs to be uploaded."
 }
 
 # Validate the command line parameters
 validate_parameter() {
-    if [ "$#" -ne 2 ]; then
-        echo "Error: Please provide both the option and file parameters."
-        print_help
-        exit 1
+    if [ "$1" = "--dry-run" ]; then
+        if [ "$#" -ne 1 ]; then
+            echo "Error: '--dry-run' mode does not accept additional arguments."
+            print_help
+            exit 1
+        fi
+        return
     fi
 
     if [ "$1" != "nightly" ] && [ "$1" != "release" ]; then
@@ -31,6 +35,12 @@ validate_parameter() {
         exit 1
     fi
 
+    if [ "$#" -ne 2 ]; then
+        echo "Error: Please provide both the option and file parameters."
+        print_help
+        exit 1
+    fi
+
     if [ ! -f "$2" ]; then
         echo "Error: File not found. Please provide a valid file path as the second parameter."
         print_help
@@ -38,12 +48,17 @@ validate_parameter() {
     fi
 }
 
-# Build documentation of ostd
+# Build documentation of all crates to publish
 build_api_docs() {
     cd "${ASTER_SRC_DIR}"
     make install_osdk
-    cd "${ASTER_SRC_DIR}/ostd"
-    cargo osdk doc
+    # Crates depend on OSTD, including OSTD itself
+    CRATES="ostd osdk/deps/frame-allocator osdk/deps/heap-allocator osdk/deps/test-kernel"
+    for CRATE in $CRATES; do
+        pushd $CRATE
+        RUSTDOCFLAGS="-Dwarnings" cargo osdk doc
+        popd
+    done
 }
 
 # Git clone the API documentation repo
@@ -118,12 +133,16 @@ validate_parameter "$@"
 SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
 ASTER_SRC_DIR=${SCRIPT_DIR}/../..
 WORK_DIR=${ASTER_SRC_DIR}/..
-SSH_KEY_FILE=$(realpath "$2")
 CLONED_REPO_DIR=temp_api_docs
 KNOWN_HOSTS_FILE="${WORK_DIR}/known_hosts"
 
 build_api_docs
 
+if [ "$1" = "--dry-run" ]; then
+    exit 0
+fi
+
+SSH_KEY_FILE=$(realpath "$2")
 if [ "$1" = "nightly" ]; then
     REPO_URL=git@github.com:asterinas/api-docs-nightly.git
     clone_repo