book.yml

name: Book

on:
  push:
    branches: [main]

# Ensures that only one workflow task will run at a time. Previous builds, if
# already in process, will get cancelled. Only the latest commit will be allowed
# to run, cancelling any workflows in between
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: read

jobs:
  changes:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      book: ${{ steps.filter.outputs.book || 'true' }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        if: github.event_name == 'pull_request'
        with:
          persist-credentials: false
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
        id: filter
        if: github.event_name == 'pull_request'
        with:
          filters: .github/path-filters.yml

  build:
    name: Build Docs
    needs: changes
    if: needs.changes.outputs.book == 'true'
    permissions:
      contents: read
      id-token: write
      statuses: write
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
        with:
          persist-credentials: false

      - name: Setup mdBook
        uses: jontze/action-mdbook@6c0be56d14c4bf16861b00af61f50ff7400ce502 #v4.0.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          mdbook-version: ~0.5
          use-linkcheck: true
          use-mermaid: true
      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 #v1.16.1
        with:
          toolchain: nightly
          cache-on-failure: true
      - uses: ./.github/actions/setup-zebra-build

      - name: Build Zebra book
        run: |
          mdbook build book --dest-dir "$(pwd)"/target/docs
        env:
          # The -A and -W settings must be the same as the `rustdocflags` in:
          # https://github.com/ZcashFoundation/zebra/blob/main/.cargo/config.toml#L87
          RUSTDOCFLAGS: --html-in-header katex-header.html -A rustdoc::private_intra_doc_links -D warnings

      - name: Build internal docs
        run: |
          cargo doc --no-deps --workspace --all-features --document-private-items --target-dir "$(pwd)"/target/internal
          # Copy internal docs to docs directory
          mkdir -p target/docs/internal
          cp -r target/internal/doc/* target/docs/internal/
        env:
          # Keep in sync with ./lint.yml:jobs.docs
          # The -A and -W settings must be the same as the `rustdocflags` in:
          # https://github.com/ZcashFoundation/zebra/blob/main/.cargo/config.toml#L87
          RUSTDOCFLAGS: --html-in-header katex-header.html -D warnings -A rustdoc::private_intra_doc_links --cfg docsrs --show-type-layout --generate-link-to-definition --enable-index-page -Zunstable-options

      - name: Include benchmark dashboard
        # Snapshots `gh-pages/dev/bench` (published by `benchmarks.yml`) into
        # the docs artifact so it is reachable at `/dev/bench`.
        run: |
          if ! git fetch origin gh-pages --depth=1 2>/dev/null; then
            echo "gh-pages branch does not exist yet, skipping benchmark dashboard"
            exit 0
          fi

          if ! git show origin/gh-pages:dev/bench/index.html >/dev/null 2>&1; then
            echo "gh-pages has no benchmark data yet, skipping benchmark dashboard"
            exit 0
          fi

          # index.html and data.js are published atomically by
          # github-action-benchmark, so data.js isn't guarded separately.
          mkdir -p target/docs/dev/bench
          git show origin/gh-pages:dev/bench/index.html > target/docs/dev/bench/index.html
          git show origin/gh-pages:dev/bench/data.js > target/docs/dev/bench/data.js

      - name: Setup Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d #v6.0.0

      - name: Upload site
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 #v5.0.0
        with:
          path: ./target/docs

  deploy:
    name: Deploy to GitHub Pages
    # Only deploy if a push to main
    # TODO: Uncomment this before merging
    # if: github.ref_name == 'main' && github.event_name == 'push'
    needs: [changes, build]
    if: needs.changes.outputs.book == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 30

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment.
    # `contents: read` is intentionally omitted: this job publishes rendered
    # source to a public site, so missing checkout permission keeps it inert
    # on private forks as a fail-closed safeguard.
    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 #v5.0.0

  book:
    runs-on: ubuntu-latest
    if: always()
    needs:
      - changes
      - build
      - deploy
    timeout-minutes: 30
    steps:
      - name: Decide whether the needed jobs succeeded or failed
        uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe #v1.2.2
        with:
          jobs: ${{ toJSON(needs) }}
          allowed-skips: build, deploy