docs.yml

name: Docs

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

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}

jobs:
  set-image:
    # GitHub Actions allows using 'env' in a container context.
    # However, env variables don't work for forks: https://github.com/orgs/community/discussions/44322
    # This workaround sets the container image for each job using 'set-image' job output.
    # TODO: remove once migration is complete or this workflow is fully stable
    if: contains(github.event.label.name, 'GHA-migration') || contains(github.event.pull_request.labels.*.name, 'GHA-migration')
    runs-on: ubuntu-latest
    outputs:
      IMAGE: ${{ steps.set_image.outputs.IMAGE }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - id: set_image
        run: cat .github/env >> $GITHUB_OUTPUT
  test-rustdoc:
    runs-on: arc-runners-polkadot-sdk-beefy
    needs: [set-image]
    container:
      image: ${{ needs.set-image.outputs.IMAGE }}
    steps:
      - uses: actions/checkout@v4
      - run: forklift cargo doc --workspace --all-features --no-deps
        env:
          SKIP_WASM_BUILD: 1
  test-doc:
    runs-on: arc-runners-polkadot-sdk-beefy
    needs: [set-image]
    container:
      image: ${{ needs.set-image.outputs.IMAGE }}
    steps:
      - uses: actions/checkout@v4
      - run: forklift cargo test --doc --workspace
        env:
          RUSTFLAGS: "-Cdebug-assertions=y -Dwarnings"

  build-rustdoc:
    runs-on: arc-runners-polkadot-sdk-beefy
    needs: [set-image, test-rustdoc]
    container:
      image: ${{ needs.set-image.outputs.IMAGE }}
    steps:
      - uses: actions/checkout@v4
      - run: forklift cargo doc --all-features --workspace --no-deps
        env:
          SKIP_WASM_BUILD: 1
          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"
      - run: rm -f ./target/doc/.lock
      - run: mv ./target/doc ./crate-docs
      - name: Inject Simple Analytics script
        run: |
          script_content="<script async defer src=\"https://apisa.parity.io/latest.js\"></script><noscript><img src=\"https://apisa.parity.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=polkadot_sdk_docs/index.html>" > ./crate-docs/index.html
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ github.sha }}-doc
          path: ./crate-docs/
          retention-days: 1
          if-no-files-found: error

  build-implementers-guide:
    runs-on: ubuntu-latest
    container:
      image: paritytech/mdbook-utils:e14aae4a-20221123
      options: --user root
    steps:
      - uses: actions/checkout@v4
      - run: mdbook build ./polkadot/roadmap/implementers-guide
      - run: mkdir -p artifacts
      - run: mv polkadot/roadmap/implementers-guide/book artifacts/
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ github.sha }}-guide
          path: ./artifacts/
          retention-days: 1
          if-no-files-found: error

  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@v4
        with:
          ref: gh-pages
      - uses: actions/create-github-app-token@v1
        id: app-token
        with:
          app-id: ${{ secrets.POLKADOTSDK_GHPAGES_APP_ID }}
          private-key: ${{ secrets.POLKADOTSDK_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@v4
        with:
          name: ${{ github.sha }}-doc
          path: ${{ github.head_ref || github.ref_name }}
      - name: Download guide
        uses: actions/download-artifact@v4
        with:
          name: ${{ github.sha }}-guide
          path: /tmp
      - run: mkdir -p book
      - name: Move book files
        run: mv /tmp/book/html/* book/
      - name: Push to GH-Pages branch
        uses: github-actions-x/commit@v2.9
        with:
          github-token: ${{ steps.app-token.outputs.token }}
          push-branch: "gh-pages"
          commit-message: "___Updated docs for ${{ github.head_ref || github.ref_name }}___"
          force-add: "true"
          files: ${{ github.head_ref || github.ref_name }}/ book/
          name: devops-parity
          email: devops-team@parity.io