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: {}

env:
  CARGO_ZEROCOPY_AUTO_INSTALL_TOOLCHAIN: 1

concurrency:
  group: deploy
  cancel-in-progress: false

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false
      - 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

      - name: Configure GitHub pages
        id: pages
        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # 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 --extend-css rustdoc/style.css'
            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 +$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@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
        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
    permissions:
      pages: write # Required for Pages deployment
      id-token: write # Required for OIDC-based Pages deployment
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4