diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..434f4f9556 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,116 @@ +# Copyright 2024 The Fuchsia Authors +# +# Licensed under a BSD-style license , Apache License, Version 2.0 +# , or the MIT +# license , 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@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 '' > 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 \ No newline at end of file