Cockatrice/.github/workflows/documentation-build.yml

name: Build Documentation

permissions:
  contents: read    # write permission to the destination repo come from 'deploy_key'

on:
  pull_request:
    paths:
      - 'doc/doxygen/**'
      - '.github/workflows/documentation-build.yml'
      - 'Doxyfile'
  release:
    types:
      - published    # publishing of stable releases and pre-releases
  workflow_dispatch:

# Cancel earlier, unfinished runs of this workflow on the same branch (unless on release)
concurrency:
  group: "${{ github.workflow }} @ ${{ github.ref_name }}"
  cancel-in-progress: ${{ github.event_name != 'release' }}

env:
  COCKATRICE_REF: ${{ github.ref_name }}    # tag name if the commit is tagged, otherwise branch name

jobs:
  docs:
    name: "Doxygen"
    runs-on: ubuntu-latest    # https://github.com/actions/runner-images#available-images

    steps:
      - name: "Checkout"
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          submodules: recursive

      - name: "Install Graphviz"
        shell: bash
        run: |
          sudo apt-get install -y graphviz
          dot -V

      - name: "Install Doxygen"
        uses: ssciwr/doxygen-install@v2
        with:
          version: "1.18.0"    # https://www.doxygen.nl/manual/changelog.html

      - name: "Update Doxygen Configuration"
        shell: bash
        run: |
          git diff Doxyfile
          doxygen -u Doxyfile
          if git diff --quiet Doxyfile; then
            echo "::notice::No config changes in Doxyfile detected."
          else
            echo "::error::Config changes in Doxyfile detected! Please update the file by running 'doxygen -u Doxyfile'."
            echo ""
            git diff --color=always Doxyfile
            exit 1
          fi

      - name: "Generate Documentation"
        if: always()
        shell: bash
        run: doxygen Doxyfile

      - name: "Deploy to cockatrice.github.io/docs"
        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
        with:
          deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }}
          destination_dir: docs    # docs will be available at https://cockatrice.github.io/docs/
          external_repository: Cockatrice/cockatrice.github.io
          publish_branch: master
          publish_dir: ./docs/html

      - name: Link to Documentation Page
        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
        shell: bash
        run: echo "::notice title=New documentation published::Shortly available at https://cockatrice.github.io/docs/"