pezkuwi-sdk/.github/workflows/docs.yml

name: Docs

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  merge_group:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  isdraft:
    uses: ./.github/workflows/reusable-isdraft.yml
  preflight:
    needs: isdraft
    uses: ./.github/workflows/reusable-preflight.yml

  test-doc:
    runs-on: ${{ needs.preflight.outputs.RUNNER }}
    timeout-minutes: 300
    needs: [preflight]
    container:
      image: ${{ needs.preflight.outputs.IMAGE }}
      volumes:
        - /cache/cargo-target/pezkuwi-sdk-docs:/cache/target
    env:
      RUSTFLAGS: "-Cdebug-assertions=y -Dwarnings"
      CARGO_INCREMENTAL: 0
      CARGO_TARGET_DIR: /cache/target
      WASM_BUILD_WORKSPACE_HINT: ${{ github.workspace }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Disable forklift cache wrapper
        run: echo "RUSTC_WRAPPER=" >> $GITHUB_ENV

      - name: Install wasm32v1-none target
        run: rustup target add wasm32v1-none

      # Clean stale caches from other workflows that ran on this VPS runner.
      # Each VPS has limited disk; leftover caches from tests/checks can fill it.
      - name: Clean stale caches
        run: |
          echo "Disk before cleanup:"
          df -h /cache 2>/dev/null || df -h /
          for dir in /cache/cargo-target/*/; do
            [ "$dir" = "/cache/cargo-target/pezkuwi-sdk-docs/" ] && continue
            echo "Removing stale cache: $dir"
            rm -rf "$dir"
          done
          echo "Disk after cleanup:"
          df -h /cache 2>/dev/null || df -h /

      # Exclude pezkuwi-zombienet-sdk-tests: its build.rs runs nested cargo build
      # which doesn't inherit workspace [patch.crates-io] settings, causing
      # serde_core duplicate lang item error. See: https://github.com/pezkuwichain/pezkuwi-sdk/issues/357
      - name: script
        id: required
        run: |
          git config --global --add safe.directory '*'
          cargo test --doc --workspace --locked --all-features --exclude pezkuwi-zombienet-sdk-tests --exclude pezpallet-revive-eth-rpc

  build-rustdoc:
    runs-on: ${{ needs.preflight.outputs.RUNNER }}
    timeout-minutes: 180
    if: ${{ always() && !cancelled() && needs.preflight.outputs.changes_rust }}
    needs: [preflight, test-doc]
    container:
      image: ${{ needs.preflight.outputs.IMAGE }}
      volumes:
        - /cache/cargo-target/pezkuwi-sdk-docs:/cache/target
    env:
      SKIP_WASM_BUILD: 1
      CARGO_INCREMENTAL: 0
      CARGO_TARGET_DIR: /cache/target
      RUSTDOCFLAGS: "-Dwarnings --default-theme=ayu --html-in-header ./docs/sdk/assets/header.html --extend-css ./docs/sdk/assets/theme.css --html-after-content ./docs/sdk/assets/after-content.html"
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Disable forklift cache wrapper
        run: echo "RUSTC_WRAPPER=" >> $GITHUB_ENV

      # Exclude pezkuwi-zombienet-sdk-tests: nested cargo build in build.rs
      # doesn't inherit workspace patches. See test-doc job comment.
      - name: script
        id: required
        run: |
          git config --global --add safe.directory '*'
          cargo doc --all-features --workspace --no-deps --locked --exclude pezkuwi-zombienet-sdk-tests --exclude pezpallet-revive-eth-rpc
      - run: rm -f ${CARGO_TARGET_DIR}/doc/.lock
      - run: mv ${CARGO_TARGET_DIR}/doc ./crate-docs
      - name: Inject Simple Analytics script
        run: |
          script_content="<script async defer src=\"https://apisa.pezkuwichain.io/latest.js\"></script><noscript><img src=\"https://apisa.pezkuwichain.io/latest.js\" alt=\"\" referrerpolicy=\"no-referrer-when-downgrade\" /></noscript>"
          docs_dir="./crate-docs"

          inject_simple_analytics() {
            find "$1" -name '*.html' | xargs -I {} -P "$(nproc)" bash -c 'file="{}"; echo "Adding Simple Analytics script to $file"; sed -i "s|</head>|'"$2"'</head>|" "$file";'
          }

          inject_simple_analytics "$docs_dir" "$script_content"
      - run: echo "<meta http-equiv=refresh content=0;url=pezkuwi_sdk_docs/index.html>" > ./crate-docs/index.html
      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: ${{ github.sha }}-doc
          path: ./crate-docs/
          retention-days: 1
          if-no-files-found: error

  build-implementers-guide:
    runs-on: ubuntu-latest
    needs: isdraft
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install mdbook
        run: |
          cargo install mdbook --version 0.4.35 --locked
      - run: mdbook build ./pezkuwi/roadmap/implementers-guide
      - run: mkdir -p artifacts
      - run: mv pezkuwi/roadmap/implementers-guide/book artifacts/
      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: ${{ github.sha }}-guide
          path: ./artifacts/
          retention-days: 1
          if-no-files-found: error

  confirm-required-jobs-passed:
    runs-on: ubuntu-latest
    name: All docs jobs passed
    # If any new job gets added, be sure to add it to this array
    needs: [test-doc, build-rustdoc, build-implementers-guide]
    if: always() && !cancelled()
    steps:
      - run: |
          tee resultfile <<< '${{ toJSON(needs) }}'
          FAILURES=$(cat resultfile | grep '"result": "failure"' | wc -l)
          if [ $FAILURES -gt 0 ]; then
            echo "### At least one required job failed ❌" >> $GITHUB_STEP_SUMMARY
            exit 1
          else
            echo '### Good job! All the required jobs passed 🚀' >> $GITHUB_STEP_SUMMARY
          fi

  publish-rustdoc:
    if: github.ref == 'refs/heads/master'
    runs-on: ubuntu-latest
    environment: subsystem-benchmarks
    needs: [build-rustdoc, build-implementers-guide]
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          ref: gh-pages
      - uses: actions/create-github-app-token@29824e69f54612133e76f7eaac726eef6c875baf # v2.2.1
        id: app-token
        with:
          app-id: ${{ secrets.PEZKUWI_GHPAGES_APP_ID }}
          private-key: ${{ secrets.PEZKUWI_GHPAGES_APP_KEY }}
      - name: Ensure destination dir does not exist
        run: |
          rm -rf book/
          rm -rf ${REF_NAME}
        env:
          REF_NAME: ${{ github.head_ref || github.ref_name }}
      - name: Download rustdocs
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
        with:
          name: ${{ github.sha }}-doc
          path: ${{ github.head_ref || github.ref_name }}
      - name: Download guide
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
        with:
          name: ${{ github.sha }}-guide
          path: /tmp
      - run: mkdir -p book
      - name: Move book files
        run: mv /tmp/book/html/* book/
      - name: Push changes to gh-pages
        env:
          TOKEN: ${{ steps.app-token.outputs.token }}
          APP_NAME: "pezkuwichain-upd-ghpages"
          REF_NAME: ${{ github.head_ref || github.ref_name }}
          Green: "\e[32m"
          NC: "\e[0m"
        run: |
          echo "${Green}Git add${NC}"
          git add book/
          git add ${REF_NAME}/

          echo "${Green}git status | wc -l${NC}"
          git status | wc -l

          echo "${Green}Add new remote with gh app token${NC}"
          git remote set-url origin $(git config remote.origin.url | sed "s/github.com/${APP_NAME}:${TOKEN}@github.com/g")

          echo "${Green}Remove http section that causes issues with gh app auth token${NC}"
          sed -i.bak '/\[http/d' ./.git/config
          sed -i.bak '/extraheader/d' ./.git/config

          echo "${Green}Git push${NC}"
          git config user.email "ci@pezkuwichain.io"
          git config user.name "${APP_NAME}"
          git commit --amend -m "___Updated docs" || echo "___Nothing to commit___"
          git push origin gh-pages --force