diff --git a/.github/workflows/update-online-api-docs.yml b/.github/workflows/update-online-api-docs.yml new file mode 100644 index 00000000..a5b8720a --- /dev/null +++ b/.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} diff --git a/docs/src/framework/README.md b/docs/src/framework/README.md index f91aa809..05d3d9eb 100644 --- a/docs/src/framework/README.md +++ b/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, diff --git a/tools/github_workflows/build_and_upload_api_docs.sh b/tools/github_workflows/build_and_upload_api_docs.sh new file mode 100755 index 00000000..4ce99bc0 --- /dev/null +++ b/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] " + 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=" + + + + + + +

Redirecting to a new page...

+ + + +" + 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