docs.yml

name: Build and store docs artifact

on:
  workflow_dispatch:
  # See https://github.com/imjohnbo/ok-to-test/tree/master for an overview
  # of how this works.
  # I officially hate GitHub for forbidding OpenID Connect tokens in forks.
  repository_dispatch:
    types: [ ok-to-test-command ]
  push:
    branches:
      - main

jobs:
  build_clis:
    name: "Build CLIs ${{ matrix.target }} (${{ matrix.os }})"
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        include:
          - target: aarch64-pc-windows-msvc
            os: windows-2022
          - target: x86_64-unknown-linux-gnu
            os: ubuntu-22.04
          - target: x86_64-apple-darwin
            os: macos-12
          - target: aarch64-apple-darwin
            os: macos-14
          - target: x86_64-pc-windows-msvc
            os: windows-2022
    steps:
      - name: Checkout repository from source repo
        if: |
          (github.event_name == 'push' && github.event.repository.full_name == github.repository)
        uses: actions/checkout@v4
      - name: Checkout repository from fork
        if: |
          github.event_name == 'repository_dispatch' &&
          github.event.client_payload.slash_command.args.named.sha != '' &&
          contains(
            github.event.client_payload.pull_request.head.sha,
            github.event.client_payload.slash_command.args.named.sha
          )
        uses: actions/checkout@v4
        with:
          ref: 'refs/pull/${{ github.event.client_payload.pull_request.number }}/merge'
      - uses: ./.github/actions/create-check
        if: ${{ github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Build CLIs ${{ matrix.target }} (${{ matrix.os }})"
          workflow: "Build and store docs artifacts"
          run_id: ${{ github.run_id }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Set BINARY_EXTENSION
        if: ${{ matrix.os != 'windows-2022' }}
        run: |
          echo "BINARY_EXTENSION=" >> $GITHUB_ENV
      - name: Set BINARY_EXTENSION
        if: ${{ matrix.os == 'windows-2022' }}
        run: |
          Add-Content $env:GITHUB_ENV "BINARY_EXTENSION=.exe" -Encoding utf8
      - name: Install Rust
        uses: actions-rust-lang/setup-rust-toolchain@v1.8.0
        with:
          cache-workspaces: "./libs -> ./target"
      - name: Build CLI
        run: |
          cd libs
          cargo build --bin pavex --bin pavexc --release
      - name: Store pavex CLI artifact
        uses: actions/upload-artifact@v4
        with:
          name: pavex_cli-${{ matrix.target }}
          path: libs/target/release/pavex${{ env.BINARY_EXTENSION }}
      - name: Store pavexc CLI artifact
        uses: actions/upload-artifact@v4
        with:
          name: pavexc_cli-${{ matrix.target }}
          path: libs/target/release/pavexc${{ env.BINARY_EXTENSION }}
      - uses: ./.github/actions/finalize-check
        if: ${{ always() && github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Build CLIs ${{ matrix.target }} (${{ matrix.os }})"
          conclusion: ${{ job.status }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

  build_tutorial_generator:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository from source repo
        if: |
          (github.event_name == 'push' && github.event.repository.full_name == github.repository)
        uses: actions/checkout@v4
      - name: Checkout repository from fork
        if: |
          github.event_name == 'repository_dispatch' &&
          github.event.client_payload.slash_command.args.named.sha != '' &&
          contains(
            github.event.client_payload.pull_request.head.sha,
            github.event.client_payload.slash_command.args.named.sha
          )
        uses: actions/checkout@v4
        with:
          ref: 'refs/pull/${{ github.event.client_payload.pull_request.number }}/merge'
      - uses: ./.github/actions/create-check
        if: ${{ github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Build tutorial generator"
          workflow: "Build and store docs artifacts"
          run_id: ${{ github.run_id }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Install Rust
        uses: actions-rust-lang/setup-rust-toolchain@v1.8.0
        with:
          rustflags: ""
          cache-workspaces: "./doc_examples/tutorial_generator -> ./target"
      - name: Build CLI
        run: |
          cd doc_examples/tutorial_generator
          cargo build
      - name: Store CLI artifact
        uses: actions/upload-artifact@v4
        with:
          name: tutorial_generator
          path: doc_examples/tutorial_generator/target/debug/tutorial_generator
      - uses: ./.github/actions/finalize-check
        if: ${{ always() && github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Build tutorial generator"
          conclusion: ${{ job.status }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

  tests:
    name: "Run tests ${{ matrix.target }} (${{ matrix.os }})"
    runs-on: ${{ matrix.os }}
    permissions:
      pull-requests: write
      checks: write
    # Either run tests because it's a PR from the same repo or a push to `main`
    if: |
      (github.event_name == 'repository_dispatch' &&
      github.event.client_payload.slash_command.args.named.sha != '' &&
      contains(
        github.event.client_payload.pull_request.head.sha,
        github.event.client_payload.slash_command.args.named.sha
      )) ||
      (github.event_name == 'push' && github.event.repository.full_name == github.repository)
    strategy:
      fail-fast: false
      matrix:
        include:
          - target: aarch64-pc-windows-msvc
            os: windows-2022
          - target: x86_64-unknown-linux-gnu
            os: ubuntu-22.04
          - target: x86_64-apple-darwin
            os: macos-12
          - target: aarch64-apple-darwin
            os: macos-14
          - target: x86_64-pc-windows-msvc
            os: windows-2022
    needs:
      - build_clis
    steps:
      - name: Checkout repository from source repo
        if: |
          github.event_name == 'push' && github.event.repository.full_name == github.repository
        uses: actions/checkout@v4
      - name: Checkout repository from fork
        if: |
          github.event_name == 'repository_dispatch' &&
          github.event.client_payload.slash_command.args.named.sha != '' &&
          contains(
            github.event.client_payload.pull_request.head.sha,
            github.event.client_payload.slash_command.args.named.sha
          )
        uses: actions/checkout@v4
        with:
          ref: 'refs/pull/${{ github.event.client_payload.pull_request.number }}/merge'
      - uses: ./.github/actions/create-check
        if: ${{ github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Run tests ${{ matrix.target }} (${{ matrix.os }})"
          workflow: "Build and store docs artifacts"
          run_id: ${{ github.run_id }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Set BINARY_EXTENSION
        if: ${{ matrix.os != 'windows-2022' }}
        run: |
          echo "BINARY_EXTENSION=" >> $GITHUB_ENV
      - name: Set BINARY_EXTENSION
        if: ${{ matrix.os == 'windows-2022' }}
        run: |
          Add-Content $env:GITHUB_ENV "BINARY_EXTENSION=.exe" -Encoding utf8
      - name: Set PAVEX
        if: ${{ matrix.os == 'macos-12' || matrix.os == 'macos-14' }}
        run: |
          echo "PAVEX=/Users/runner/.cargo/bin/pavex${BINARY_EXTENSION}" >> $GITHUB_ENV
          echo "PAVEXC=/Users/runner/.cargo/bin/pavexc${BINARY_EXTENSION}" >> $GITHUB_ENV
      - name: Set PAVEX
        if: ${{ matrix.os == 'ubuntu-22.04' }}
        run: |
          echo "PAVEX=/home/runner/.cargo/bin/pavex${BINARY_EXTENSION}" >> $GITHUB_ENV
          echo "PAVEXC=/home/runner/.cargo/bin/pavexc${BINARY_EXTENSION}" >> $GITHUB_ENV
      - name: Set PAVEX
        if: ${{ matrix.os == 'windows-2022' }}
        run: |
          Add-Content $env:GITHUB_ENV "PAVEX=C:\Users\runneradmin\.cargo\bin\pavex${BINARY_EXTENSION}" -Encoding utf8
          Add-Content $env:GITHUB_ENV "PAVEXC=C:\Users\runneradmin\.cargo\bin\pavexc${BINARY_EXTENSION}" -Encoding utf8
      - name: Install Rust nightly toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: nightly
          components: rust-docs-json, rustfmt
          rustflags: ""
          cache: false
      - name: Install Rust stable toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1.8.0
        with:
          components: rustfmt
          rustflags: ""
          cache-workspaces: "./libs -> ./target"
      - name: Download pavex CLI artifact
        uses: actions/download-artifact@v4
        with:
          name: pavex_cli-${{ matrix.target }}
          path: ~/.cargo/bin
      - name: Download pavexc CLI artifact
        uses: actions/download-artifact@v4
        with:
          name: pavexc_cli-${{ matrix.target }}
          path: ~/.cargo/bin
      - name: Mark pavex as executable
        if: ${{ matrix.os != 'windows-2022' }}
        run: chmod +x ${{ env.PAVEX }}
      - name: Activate pavex
        env:
          PAVEX_ACTIVATION_KEY: ${{ secrets.pavex_activation_key }}
        run: |
          pavex self activate
      - name: Mark pavexc as executable
        if: ${{ matrix.os != 'windows-2022' }}
        run: chmod +x ${{ env.PAVEXC }}
      - name: Run tests
        working-directory: libs
        run: |
          cargo test --no-run
          cargo test --workspace --exclude="pavex_cli"
      - name: Run UI tests
        env:
          PAVEX_TEST_CLI_PATH: ${{ env.PAVEX }}
          PAVEXC_TEST_CLI_PATH: ${{ env.PAVEXC }}
        working-directory: libs
        run: |
          cargo test --package pavex_cli
      - uses: ./.github/actions/finalize-check
        if: ${{ always() && github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Run tests ${{ matrix.target }} (${{ matrix.os }})"
          conclusion: ${{ job.status }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

  is_up_to_date:
    runs-on: ubuntu-latest
    env:
      PAVEX_PAVEXC: "/home/runner/.cargo/bin/pavexc"
    needs:
      - build_clis
      - build_tutorial_generator
    permissions:
      pull-requests: write
      checks: write
    # Either run tests because it's a PR from the same repo, or a push to `main`
    if: |
      (github.event_name == 'repository_dispatch' &&
      github.event.client_payload.slash_command.args.named.sha != '' &&
      contains(
        github.event.client_payload.pull_request.head.sha,
        github.event.client_payload.slash_command.args.named.sha
      )) ||
      (github.event_name == 'push' && github.event.repository.full_name == github.repository)
    steps:
      - name: Checkout repository from source repo
        if: |
          (github.event_name == 'push' && github.event.repository.full_name == github.repository)
        uses: actions/checkout@v4
      - name: Checkout repository from fork
        if: |
          github.event_name == 'repository_dispatch' &&
          github.event.client_payload.slash_command.args.named.sha != '' &&
          contains(
            github.event.client_payload.pull_request.head.sha,
            github.event.client_payload.slash_command.args.named.sha
          )
        uses: actions/checkout@v4
        with:
          ref: 'refs/pull/${{ github.event.client_payload.pull_request.number }}/merge'
      - uses: ./.github/actions/create-check
        if: ${{ github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Check if up to date"
          workflow: "Build and store docs artifacts"
          run_id: ${{ github.run_id }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Set git identity
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "ci@pavex.dev"
      - name: Install Rust nightly toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: nightly
          components: rust-docs-json, rustfmt
          rustflags: ""
          cache: false
      - name: Install Rust stable toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1.8.0
        with:
          rustflags: ""
          components: rustfmt
          cache-workspaces: "./libs -> ./target"
      - name: Download pavex CLI artifact
        uses: actions/download-artifact@v4
        with:
          name: pavex_cli-x86_64-unknown-linux-gnu
          path: ~/.cargo/bin
      - name: Download pavexc CLI artifact
        uses: actions/download-artifact@v4
        with:
          name: pavexc_cli-x86_64-unknown-linux-gnu
          path: ~/.cargo/bin
      - name: Mark pavex as executable
        run: chmod +x ~/.cargo/bin/pavex
      - name: Activate pavex
        env:
          PAVEX_ACTIVATION_KEY: ${{ secrets.pavex_activation_key }}
        run: |
          pavex self activate
      - name: Mark pavexc as executable
        run: chmod +x ~/.cargo/bin/pavexc
      - name: Download tutorial_generator CLI artifact
        uses: actions/download-artifact@v4
        with:
          name: tutorial_generator
          path: ~/.cargo/bin
      - name: Mark as executable
        run: chmod +x ~/.cargo/bin/tutorial_generator
      - uses: cargo-bins/cargo-binstall@main
      - name: Install cargo-px
        run: cargo binstall -y --github-token=${{ secrets.GITHUB_TOKEN }} cargo-px@0.1
      - name: Install exa
        run: cargo binstall -y --github-token=${{ secrets.GITHUB_TOKEN }} exa@0.10
      - name: Verify tutorials
        run: |
          cd doc_examples
          RUST_BACKTRACE=0 tutorial_generator --verify
      - uses: ./.github/actions/finalize-check
        if: ${{ always() && github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Check if up to date"
          conclusion: ${{ job.status }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

  build_docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository from source repo
        if: |
          (github.event_name == 'push' && github.event.repository.full_name == github.repository)
        uses: actions/checkout@v4
      - name: Checkout repository from fork
        if: |
          github.event_name == 'repository_dispatch' &&
          github.event.client_payload.slash_command.args.named.sha != '' &&
          contains(
            github.event.client_payload.pull_request.head.sha,
            github.event.client_payload.slash_command.args.named.sha
          )
        uses: actions/checkout@v4
        with:
          ref: 'refs/pull/${{ github.event.client_payload.pull_request.number }}/merge'
      - uses: ./.github/actions/create-check
        if: ${{ github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Build docs"
          workflow: "Build and store docs artifacts"
          run_id: ${{ github.run_id }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Install Rust stable toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1.8.0
        with:
          cache-workspaces: "./libs -> ./target"
      - name: Build API reference
        run: |
          cd libs
          cargo doc --package pavex --package pavex_cli_client --no-deps
      - name: Copy API reference files
        run: |
          mkdir -p docs/api_reference
          cp -r libs/target/doc/* docs/api_reference
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Build and export to Docker
        uses: docker/build-push-action@v5
        with:
          context: docs/
          load: true
          tags: pavex-docs
      - name: Build docs
        run: |
          docker run --rm -v ${PWD}:/docs pavex-docs build
      - uses: actions/upload-artifact@v4
        with:
          name: docs
          path: site/
      - name: Fix base
        run: |
          # Convert all "absolute" guide links in the reference to relative links so that we can scan for dead links
          sudo find . -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
          sudo find . -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
      - name: Link Checker
        uses: lycheeverse/lychee-action@v1
        with:
          fail: true
          args: |
            --base site 
            --exclude-loopback 
            --exclude-path="site/api_reference/pavex/http" 
            --exclude-path="site/api_reference/pavex/time" 
            --exclude-path="site/api_reference/help.html" 
            --exclude-path="site/api_reference/settings.html" 
            --exclude="https://doc.rust-lang.org/*" 
            --exclude="https://stackoverflow.com/*" 
            --exclude="https://github.com/LukeMathWalker/pavex/edit/main/*"
            --exclude="https://docs.rs/**/*" 
            --exclude-path="site/api_reference/static.files" 
            --exclude="https://fonts.gstatic.com" 
            --require-https 
            --no-progress 
            site
      - uses: ./.github/actions/finalize-check
        if: ${{ always() && github.event_name != 'push' }}
        with:
          pr_number: ${{ github.event.client_payload.pull_request.number }}
          job: "Build docs"
          conclusion: ${{ job.status }}
          github_token: ${{ secrets.GITHUB_TOKEN }}