docs.yml

# Copyright 2024 The Fuchsia Authors
#
# Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
# <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
# license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
# This file may not be copied, modified, or distributed except according to
# those terms.

# Publish every commit from `main` to google.github.io/zerocopy.

name: Publish Rustdoc on GitHub Pages
on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: deploy
  cancel-in-progress: false

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4.2.0
      - name: Configure environment variables
        run: |
          set -eo pipefail
  
          # We use toolchain descriptors ("msrv", "stable", "nightly", and
          # values from the "metadata.build-rs" key in Cargo.toml) in the
          # matrix. This step converts the current descriptor to a particular
          # toolchain version by looking up the corresponding key in
          # `Cargo.toml`. It sets the `ZC_NIGHTLY_TOOLCHAIN` environment
          # variable for use in the next step (toolchain installation) because
          # GitHub variable interpolation doesn't support running arbitrary
          # commands. In other words, we can't rewrite:
          #
          #   toolchain: $ {{ env.ZC_NIGHTLY_TOOLCHAIN }}
          #
          # ...to:
          #
          #   toolchain: $ {{ ./cargo.sh --version matrix.toolchain }} # hypothetical syntax
          ZC_NIGHTLY_TOOLCHAIN="$(./cargo.sh --version nightly)"
          echo "Found that the 'nightly' toolchain is $ZC_NIGHTLY_TOOLCHAIN" | tee -a $GITHUB_STEP_SUMMARY
          echo "ZC_NIGHTLY_TOOLCHAIN=$ZC_NIGHTLY_TOOLCHAIN" >> $GITHUB_ENV
  
      # On our MSRV, `cargo` does not know about the `rust-version` field. As a
      # result, in `cargo.sh`, if we use our MSRV toolchain in order to run `cargo
      # metadata`, we will not be able to extract the `rust-version` field. Thus,
      # in `cargo.sh`, we explicitly do `cargo +stable metadata`. This requires a
      # (more recent) stable toolchain to be installed. As of this writing, this
      # toolchain is not used for anything else.
      - name: Install stable Rust for use in 'cargo.sh'
        uses: dtolnay/rust-toolchain@00b49be78f40fba4e87296b2ead62868750bdd83 # stable
        with:
          toolchain: stable
          # This isn't actually required to build docs, but `cargo.sh` checks
          # for it in order to help avoid the subtle UI test bugs that happen
          # when UI tests are run without it installed.
          components: rust-src
  
      - name: Install Rust with nightly toolchain (${{ env.ZC_NIGHTLY_TOOLCHAIN }})
        uses: dtolnay/rust-toolchain@00b49be78f40fba4e87296b2ead62868750bdd83 # stable
        with:
            toolchain: ${{ env.ZC_NIGHTLY_TOOLCHAIN }}
            targets: "x86_64-unknown-linux-gnu"

      - name: Configure GitHub pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Cargo doc
        # We pass --document-private-items and --document-hidden items to ensure
        # that documentation always builds even for these items. This makes
        # future changes to make those items public/non-hidden more painless.
        # Note that --document-hidden-items is unstable; if a future release
        # breaks or removes it, we can just update CI to no longer pass that
        # flag.
        run: |
            # Include arguments passed during docs.rs deployments to make sure those
            # work properly.
            #
            # TODO(#1228): Use `jq` to parse these from `Cargo.toml` instead of
            # hard-coding them once we've gotten it working again.
            METADATA_DOCS_RS_RUSTDOC_ARGS='--cfg doc_cfg --generate-link-to-definition'
            export RUSTDOCFLAGS="-Z unstable-options --document-hidden-items $METADATA_DOCS_RS_RUSTDOC_ARGS"

            # TODO: Use `./cargo.sh` instead once we've debugged why it won't work.
            cargo +${{ env.ZC_NIGHTLY_TOOLCHAIN }} doc --document-private-items --package zerocopy --all-features

      - name: Add HTML redirect to doc root
        # By default, Rustdoc doesn't redirect to the documentation root, so we
        # manually generate a redirect.
        run: echo '<meta http-equiv="refresh" content="0;url=zerocopy/index.html">' > target/doc/index.html

      - name: Upload Cargo doc output to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: target/doc
  deploy:
    name: Deploy to GitHub Pages
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4