[ci] Publish cargo doc to GitHub Pages

Author: joshlf

.github/workflows/docs.yml

@@ -0,0 +1,114 @@
+# 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.
+
+name: Publish Rustdoc on GitHub Pages
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+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@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
+      - 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@v4
+
+      - 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=aoc/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