Use GitHub actions to build and publish Rust docs

.github/workflows/build_rust_docs.yaml

@@ -0,0 +1,62 @@
+name: Build Rust docs
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  build_rust_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v2
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+          path: out
+
+      # We need to set up git user details before we can perform git operations.
+      - name: Git setup
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "GitHub Actions"
+
+      # Copied from https://github.com/jens-maus/RaspberryMatic/blob/ea6b8ce0dd2d53ea88b2766ba8d7f8e1d667281f/.github/workflows/ci.yml#L34-L40
+      - name: free disk space
+        run: |
+          df --human-readable
+          sudo swapoff --all
+          sudo rm --force /swapfile
+          sudo apt clean
+          docker rmi $(docker image ls --all --quiet)
+          df --human-readable
+
+      # Build Docker image, caching from the latest version from the remote repository.
+      - name: Docker build
+        timeout-minutes: 30
+        run: |
+          docker pull gcr.io/oak-ci/oak:latest
+          docker build --pull --cache-from=gcr.io/oak-ci/oak:latest --tag=gcr.io/oak-ci/oak:latest .
+
+      # Remove all files from the "out" folder.
+      - name: Clear "out" folder
+        run: rm --recursive --force ./out/*
+
+      # Generate docs from within the Docker image.
+      - name: Generate docs
+        run: ./scripts/docker_run ./scripts/build_gh_pages ./out
+
+      # From the "out" folder, commit the results and push to gh-pages.
+      # This step only applies to `push` events (not `pull_request`).
+      - name: Commit and push (post-merge only)
+        if: github.event_name == 'push'
+        run: |
+          cd ./out
+          git add .
+          git commit --message="Update gh-pages from ${GITHUB_SHA}"
+          git push

scripts/build_gh_pages

@@ -1,38 +1,39 @@
 #!/usr/bin/env bash
+#
+# Script to generate documentation for Rust crates to publish as gh-pages.
+#
+# Usage:
+#
+# ./scipts/build_gh_pages <target_dir>
+#
+# Where <target_dir> must be an empty directory.
 
 readonly SCRIPTS_DIR="$(dirname "$0")"
 # shellcheck source=scripts/common
 source "$SCRIPTS_DIR/common"
 
-# First check if the current commit is "clean" with respect to the master branch.
-readonly BRANCH="$(git rev-parse --abbrev-ref HEAD)"
-([[ "${BRANCH}" == 'master' ]] && git diff --exit-code master && git diff --cached --exit-code master) \
-  || (echo "please commit any pending changes first and run this script from the master branch"; exit 1)
+readonly TARGET_DIR="${1:-}"
 
-readonly BRANCH_SHA1=$(git rev-parse --short=12 HEAD)
-readonly BRANCH_SUBJECT=$(git log -n 1 --format=format:%s)
-readonly COMMIT_MESSAGE=$(cat <<-END
-Update gh-pages from ${BRANCH_SHA1}
+if [[ -z "${TARGET_DIR}" ]]; then
+  echo 'target dir not specified'
+  exit 1
+fi
 
-Auto-generated from commit ${BRANCH_SHA1} ("${BRANCH_SUBJECT}").
-END
-)
-
-# Create a temporary directory to stage the output of the generation process.
-readonly TARGET_DIR=$(mktemp --directory --tmpdir=/tmp 'project-oak-gh-pages-XXXXXXXXXX')
+if [[ ! -d "${TARGET_DIR}" ]]; then
+  echo 'target not a directory'
+  exit 1
+fi
 
-# Clone the gh-pages branch to the target directory, limiting to one commit.
-git clone [email protected]:project-oak/oak.git --branch=gh-pages --depth=1 "${TARGET_DIR}"
+if [[ ! -z "$(ls "${TARGET_DIR}"/*)" ]]; then
+  echo 'target dir not empty'
+  exit 1
+fi
 
-# Remove everything from the target directory. This script is supposed to automatically recreate
-# everything within that directory.
-rm --recursive --force "${TARGET_DIR:?}"/*
+# Generate docs directly in the target dir.
+cargo doc --no-deps --target-dir="${TARGET_DIR}"
 
-# Remove previously generated artifacts, since `cargo doc` only regenerates new or modified
-# files, but does not remove artifacts generated from now-removed files.
-rm --recursive --force ./target/doc
-cargo doc --no-deps
-cp --recursive ./target/doc "${TARGET_DIR}"
+# Remove non-doc artifacts from the target dir.
+rm --recursive --force "${TARGET_DIR}/debug"
 
 # The docs generated from the Cargo workspace do not include a workspace-level index, so we generate
 # one here and redirect to the Oak SDK documentation.
@@ -47,12 +48,3 @@ cat <<-END > "${TARGET_DIR}/index.html"
   </body>
 </html>
 END
-
-(
-  cd "${TARGET_DIR}"
-  # Stage everything for commit, including the `index.html` page.
-  git add .
-  git commit --message="${COMMIT_MESSAGE}"
-  echo "to push changes, run the following command:"
-  echo "(cd ${TARGET_DIR} && git push)"
-)

scripts/docker_run

@@ -28,7 +28,6 @@ docker build \
 
 docker_run_flags=(
   '--interactive'
-  '--tty'
   '--rm'
   "--user=$DOCKER_UID:$DOCKER_GID"
   "--env=USER=$DOCKER_USER"
@@ -41,6 +40,11 @@ docker_run_flags=(
   '--network=host'
 )
 
+# Some CI systems (GitHub actions) do not run with a real TTY attached.
+if [[ -z "${CI:-}" ]]; then
+  docker_run_flags+=('--tty')
+fi
+
 if [[ "$1" == '--detach' ]]; then
   docker_run_flags+=('--detach')
   docker run "${docker_run_flags[@]}" "$DOCKER_IMAGE_NAME:latest" "${@:2}"