Add CI to update API documentations

.github/workflows/update-online-api-docs.yml

@@ -0,0 +1,43 @@
+name: Update Online API Docs
+
+on:
+  # 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:
+  build_and_upload:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    container: asterinas/asterinas:0.4.2
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          repository: 'asterinas/asterinas'
+          path: 'asterinas'
+
+      - name: Build & Upload Nightly API Docs
+        if: github.event_name == 'schedule'
+        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}
+          bash asterinas/tools/github_workflows/build_and_upload_api_docs.sh nightly ${KEY_FILE} 
+
+      - name: Build & Upload Release API Docs
+        if: github.event_name == 'push'
+        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}
+          bash asterinas/tools/github_workflows/build_and_upload_api_docs.sh release ${KEY_FILE} 

docs/src/framework/README.md

@@ -38,6 +38,11 @@ Most of these APIs fall into the following categories:
 To explore how these APIs come into play,
 see [the example of a 100-line kernel in safe Rust](a-100-line-kernel.md).
 
+The framework APIs have been extensively documented.
+You can access the comprehensive API documentation for each release by visiting the [API docs](https://asterinas.github.io/api-docs).
+Additionally, you can refer to the latest nightly version API documentation at [API docs nightly](https://asterinas.github.io/api-docs-nightly),
+which remains in sync with the latest changes in the main branch.
+
 ## Four Requirements Satisfied
 
 In designing and implementing Asterinas Framework,

tools/github_workflows/build_and_upload_api_docs.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+
+# SPDX-License-Identifier: MPL-2.0
+
+set -e
+
+# This script is used to build API documentations 
+# and upload the documentation to self-hosted repos.
+
+# Print help message
+print_help() {
+    echo "Usage: $0 [nightly | 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"
+}
+
+# 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
+    fi
+
+    if [ "$1" != "nightly" ] && [ "$1" != "release" ]; then
+        echo "Error: Invalid option. Please provide either 'nightly' or 'release' as the first parameter."
+        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
+        exit 1
+    fi
+}
+
+# Build documentation of aster-frame
+build_api_docs() {
+    cd "${ASTER_SRC_DIR}"
+    make install_osdk
+    cd "${ASTER_SRC_DIR}/framework/aster-frame"
+    cargo osdk doc
+}
+
+# Git clone the API documentation repo
+clone_repo() {
+    cd "${WORK_DIR}"
+    chmod 600 "${SSH_KEY_FILE}"
+    ssh-keygen -y -f "${SSH_KEY_FILE}" > /dev/null
+    ssh-keyscan -t rsa github.com >> "${KNOWN_HOSTS_FILE}"
+    git config --global user.email "github-actions[bot]@users.noreply.github.com"
+    git config --global user.name "github-actions[bot]"
+    GIT_SSH_COMMAND="ssh -i ${SSH_KEY_FILE} -o UserKnownHostsFile=${KNOWN_HOSTS_FILE}" git clone "${REPO_URL}" "${CLONED_REPO_DIR}"
+}
+
+# Generate the index.html for redirecting
+generate_redirect_index_html() {
+    local URL="$1"
+    TEMPLATE="
+<!DOCTYPE html>
+<html>
+<head>
+    <meta http-equiv=\"refresh\" content=\"0; URL=${URL}\">
+</head>
+<body>
+    <p>Redirecting to a new page...</p>
+    <script>
+        // If the browser doesn't support automatic redirection, display a link for manual redirection
+        window.location.href = \"${URL}\";
+    </script>
+</body>
+</html>
+"
+    echo -e "${TEMPLATE}" > index.html
+}
+
+# Update the nightly documentation and upload
+update_nightly_doc() {
+    cd "${WORK_DIR}/${CLONED_REPO_DIR}"
+    git checkout --orphan new_branch
+    rm -rf *
+    cp -r ${ASTER_SRC_DIR}/target/x86_64-unknown-none/doc/* ./
+    generate_redirect_index_html "https://asterinas.github.io/api-docs-nightly/aster_frame"
+    git add .
+    git commit -am "Update nightly API docs"
+    git branch -D main
+    git branch -m main
+    GIT_SSH_COMMAND="ssh -i ${SSH_KEY_FILE} -o UserKnownHostsFile=${KNOWN_HOSTS_FILE}" git push -f origin main
+    cd "${WORK_DIR}" && rm -rf "${WORK_DIR}/${CLONED_REPO_DIR}"
+}
+
+# Update the release documentation and upload
+update_release_doc() {
+    cd "${WORK_DIR}/${CLONED_REPO_DIR}"
+    VERSION=$(cat "${ASTER_SRC_DIR}/VERSION")
+    git rm -rf "${VERSION}"
+    mkdir "${VERSION}"
+    cp -r ${ASTER_SRC_DIR}/target/x86_64-unknown-none/doc/* ${VERSION}/
+    generate_redirect_index_html "https://asterinas.github.io/api-docs/${VERSION}/aster_frame"
+    git add .
+    git commit -am "Update API docs to v${VERSION}"
+    GIT_SSH_COMMAND="ssh -i ${SSH_KEY_FILE} -o UserKnownHostsFile=${KNOWN_HOSTS_FILE}" git push -f origin main
+    cd "${WORK_DIR}" && rm -rf "${WORK_DIR}/${CLONED_REPO_DIR}"
+}
+
+# Check if help message should be printed
+if [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+    print_help
+    exit 0
+fi
+
+# Validate and retrieve script parameters
+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" = "nightly" ]; then
+    REPO_URL=git@github.com:asterinas/api-docs-nightly.git
+    clone_repo
+    update_nightly_doc
+elif [ "$1" = "release" ]; then
+    REPO_URL=git@github.com:asterinas/api-docs.git
+    clone_repo
+    update_release_doc
+else
+    echo "Error: Invalid option. Please provide either 'nightly' or 'release' as the first parameter."
+    print_help
+    exit 1
+fi