build_rust_docs.yaml

name: Build Rust docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# See https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#example-using-concurrency-to-cancel-any-in-progress-job-or-run
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

jobs:
  build_rust_docs:
    runs-on: ubuntu-20.04

    permissions:
      contents: write

    steps:
      - name: Checkout branch
        uses: actions/checkout@v3

      - name: Checkout gh-pages
        uses: actions/checkout@v3
        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 "actions@github.com"
          git config --global user.name "GitHub Actions"

      # See build.yaml.
      - name: Free disk space
        run: |
          set -o errexit
          set -o xtrace
          df --human-readable
          sudo apt-get remove --yes \
              '^dotnet-.*' '^llvm-.*' 'php.*' azure-cli \
              hhvm google-chrome-stable firefox powershell
          df --human-readable
          sudo apt-get autoremove --yes
          df --human-readable
          sudo apt clean
          df --human-readable
          docker rmi $(docker image ls --all --quiet)
          df --human-readable
          rm --recursive --force "${AGENT_TOOLSDIRECTORY}"
          df --human-readable

      - uses: DeterminateSystems/nix-installer-action@677cbc8aa1fe7e80b1fd15243ec41d5e0c7e3669
      - uses: DeterminateSystems/magic-nix-cache-action@5cc3a5e24b688cf7e0ea986ab07a9d3d32c34a95

      # Remove all files from the "out" folder.
      - name: Clear "out" folder
        run: rm --recursive --force ./out/*

      # Build the Nix shell in a separate step first, so we can keep track of its build time.
      # We use the `rust` shell here and below, since it avoids building unnecessary dependencies.
      - name: Build nix shell
        run: |
          nix develop .#rust --command echo done

      # Generate docs from within the Nix shell.
      - name: Generate docs
        run: |
          nix develop .#rust --command ./scripts/build_gh_pages ./out

      # From the "out" folder, commit the results and push to the `gh-pages` branch.
      # This step only applies to `push` events (not `pull_request`), and only if there are actual
      # changes to commit in the "out" folder.
      - name: Commit and push (post-merge only)
        if: github.event_name == 'push'
        run: |
          cd ./out
          git add .
          if [[ -n "$(git status --porcelain)" ]]; then
            git commit --message="Update gh-pages from ${GITHUB_SHA}"
            git push
          else
            echo 'no changes to commit'
          fi