docs: deploy documents generated by crago doc to github pages

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  doc:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [riscv64]
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions-rs/toolchain@v1
+      with:
+        profile: minimal
+        toolchain: nightly
+        override: true
+    - name: Build docs
+      run: |
+        make doc ARCH=${{ matrix.arch }}
+        if [ "${{ matrix.arch }}" = "x86_64" ]; then
+          cp -r target/x86_64-unknown-none/doc gh-pages
+        elif [ "${{ matrix.arch }}" = "aarch64" ]; then
+          cp -r target/aarch64-unknown-none-softfloat/doc gh-pages
+        elif [ "${{ matrix.arch }}" = "riscv64" ]; then
+          cp -r target/riscv64gc-unknown-none-elf/doc gh-pages
+        fi
+    - name: Deploy to Github Pages
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        single-commit: true
+        branch: gh-pages-${{ matrix.arch }}
+        folder: gh-pages

Makefile

@@ -88,7 +88,7 @@ clippy:
 	cargo clippy --target $(TARGET)
 
 doc:
-	cargo doc --no-deps --target $(TARGET)
+	$(call cargo_doc)
 
 fmt:
 	cargo fmt --all

README.md

@@ -1,6 +1,7 @@
 # ArceOS
 
 [![CI](https://github.com/rcore-os/arceos/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/rcore-os/arceos/actions)
+[![Docs](https://img.shields.io/badge/docs-pages-green)](https://rcore-os.github.io/arceos/)
 
 An experimental modular operating system (or unikernel) written in Rust.
 
@@ -50,6 +51,14 @@ The currently supported applications (Rust), as well as their dependent modules
 
 ## Build & Run
 
+### Install build dependencies
+
+Install [cargo-binutils](https://github.com/rust-embedded/cargo-binutils) to use `rust-objcopy` and `rust-objdump` tools:
+
+```bash
+cargo install cargo-binutils
+```
+
 ### Example apps
 
 ```bash

crates/kernel_guard/src/lib.rs

@@ -1,3 +1,6 @@
+//! RAII wrappers to create a critical section with local IRQs or preemption
+//! disabled, used to implement spin locks in kernel.
+
 #![no_std]
 #![feature(asm_const)]
 #![allow(clippy::new_without_default)]

crates/spinlock/src/base.rs

@@ -18,7 +18,7 @@ use kernel_guard::BaseGuard;
 /// A [spin lock](https://en.m.wikipedia.org/wiki/Spinlock) providing mutually exclusive access to data.
 ///
 /// For single-core systems (without the "smp" feature), we remove the lock state,
-/// CPU can always get the lock if we follow the proper [`SpinLockStrategy`] in use.
+/// CPU can always get the lock if we follow the proper guard in use.
 pub struct BaseSpinLock<G: BaseGuard, T: ?Sized> {
     _phantom: PhantomData<G>,
     #[cfg(feature = "smp")]

crates/spinlock/src/lib.rs

@@ -1,3 +1,6 @@
+//! A `no_std` spin lock implementation, can disable kernel local IRQs or
+//! preemption on locking.
+
 #![cfg_attr(not(test), no_std)]
 #![feature(const_trait_impl)]
 
@@ -32,5 +35,5 @@ pub type SpinNoIrqGuard<'a, T> = BaseSpinLockGuard<'a, NoPreemptIrqSave, T>;
 /// or never be used in interrupt handlers.
 pub type SpinRaw<T> = BaseSpinLock<NoOp, T>;
 
-/// A guard that provides mutable data access for [`SpinLockRaw`].
+/// A guard that provides mutable data access for [`SpinRaw`].
 pub type SpinRawGuard<'a, T> = BaseSpinLockGuard<'a, NoOp, T>;

scripts/make/cargo.mk

@@ -49,3 +49,8 @@ endif
 define cargo_build
   cargo build $(build_args) $(1)
 endef
+
+define cargo_doc
+  RUSTDOCFLAGS="--enable-index-page -Zunstable-options" \
+  cargo doc --no-deps --target $(TARGET) --workspace --exclude "arceos-*"
+endef