deploy.yml

name: Deploy

on:
  push:
    branches:
      - main
  schedule:
    - cron: 0 1 * * *  # daily
  workflow_dispatch:

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  list-docs:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.make-matrix.outputs.matrix }}
      index_json: ${{ steps.make-matrix.outputs.index_json }}
      hash: ${{ steps.check-hash.outputs.hash }}
      changed: ${{ steps.check-hash.outputs.changed }}
    env:
      # This option controls which branches/tags are included in the documentation.
      list_docs_options: -d master -m v4.3.1 -e v5.0.0-beta.1 -s
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v6

      - name: Build docs index
        id: make-matrix
        run: |
          ./scripts/list-docs.sh ${{ env.list_docs_options }} >_index.json
          cat _index.json

          matrix="$(jq -c '{include: .docs}' _index.json)"
          echo "matrix=$matrix" >>"$GITHUB_OUTPUT"

          index_json="$(jq -cS . _index.json)"
          echo "index_json=$index_json" >>"$GITHUB_OUTPUT"
          echo "$index_json" >_index.json

      - name: Compute hash and check if updated
        id: check-hash
        env:
          hash: ${{ hashFiles('_index.json', 'scripts/make-docs.sh', 'scripts/update-index.sh', 'docs/_config.yml') }}
        run: |
          changed=true
          git fetch --no-tags origin pages-state:refs/remotes/origin/pages-state 2>/dev/null || :
          if git show origin/pages-state:.pages.hash >/dev/null 2>&1; then
            old_hash=$(git show origin/pages-state:.pages.hash | tr -d '\r\n')
            if [ "$hash" = "$old_hash" ]; then
              changed=false
            fi
          fi
          echo "changed=$changed" >>"$GITHUB_OUTPUT"
          echo "hash=$hash" >>"$GITHUB_OUTPUT"

  build-docs:
    name: build-docs (${{ matrix.dir }})
    needs: list-docs
    runs-on: ubuntu-latest
    outputs:
      index_json: ${{ needs.list-docs.outputs.index_json }}
      hash: ${{ needs.list-docs.outputs.hash }}
      changed: ${{ needs.list-docs.outputs.changed }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.list-docs.outputs.matrix) }}
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v6

      - name: Cache docs
        id: cache-docs
        uses: actions/cache@v5
        with:
          path: docs/${{ matrix.dir }}
          key: docs-${{ matrix.dir }}-${{ matrix.ref }}-${{ matrix.dev }}-${{ hashFiles('scripts/make-docs.sh') }}

      - name: Install dependencies
        if: steps.cache-docs.outputs.cache-hit != 'true' && needs.list-docs.outputs.changed == 'true'
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends doxygen-latex graphviz groff latex2html

      - name: Build docs
        if: steps.cache-docs.outputs.cache-hit != 'true' && needs.list-docs.outputs.changed == 'true'
        run: ./scripts/make-docs.sh ${{ matrix.dev && '-d ' || '' }}${{ matrix.ref }} docs/${{ matrix.dir }}

      - name: Upload docs artifact
        if: needs.list-docs.outputs.changed == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: docs-${{ matrix.dir }}
          path: |
            docs/${{ matrix.dir }}
            workaround/for/upload-artifact/issues/174  # See: https://github.com/actions/upload-artifact/issues/174
          if-no-files-found: error

  collect-docs:
    needs: build-docs
    if: needs.build-docs.outputs.changed == 'true'
    runs-on: ubuntu-latest
    outputs:
      hash: ${{ needs.build-docs.outputs.hash }}
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v6

      - name: Download all docs artifacts
        uses: actions/download-artifact@v8
        with:
          merge-multiple: true

      - name: Build docs index page
        run: |
          echo '${{ needs.build-docs.outputs.index_json }}' >_index.json
          ./scripts/update-index.sh _index.json docs
          cat docs/index.md

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v5

      - name: Build site with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: docs
          destination: _site

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: _site

  deploy-docs:
    needs: collect-docs
    runs-on: ubuntu-latest
    outputs:
      hash: ${{ needs.collect-docs.outputs.hash }}
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # Prerequisite: The following repository setting is required:
      # Pages -> Build and deployment -> Source: GitHub Actions
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  update-state:
    needs: deploy-docs
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v6

      - name: Update pages-state hash
        run: |
          git fetch --no-tags origin pages-state:refs/remotes/origin/pages-state 2>/dev/null || :
          if git show-ref --verify --quiet refs/remotes/origin/pages-state; then
            git switch -c pages-state --track origin/pages-state 2>/dev/null || git switch pages-state
          else
            git switch --orphan pages-state
          fi
          echo '${{ needs.deploy-docs.outputs.hash }}' >.pages.hash
          git add .pages.hash
          git -c user.name='github-actions[bot]' \
              -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
              commit -m 'chore(pages): update deployed hash' || true
          git push origin pages-state