name: Build documentation

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

env:
  DOXYGEN_VERSION: 1.9.4
  FORCE_COLOR: "1"

jobs:
  cache-doxygen:
    uses: ./.github/workflows/cache_doxygen.yml

  build:
    needs: cache-doxygen
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3"
        cache: 'pip'

    - name: Install apt dependencies
      run: |
        sudo apt-get -y update
        sudo apt-get -y install graphviz

    - uses: actions/cache/restore@v4
      id: cache-doxygen
      with:
        path: doxygen-bin-arc
        fail-on-cache-miss: true
        key: ${{ runner.os }}-doxygen-${{ env.DOXYGEN_VERSION }}

    - name: Install doxygen
      # at some point actions/cache/restore@4 started unpacking doxygen.tar.gz
      # automatically and I don't know why -- Rouslan
      run: |
        cd doxygen-bin-arc
        if test -d doxygen; then
          cd doxygen
        else
          gunzip doxygen.tar.gz
          tar xf doxygen.tar
          cd doxygen-${{ env.DOXYGEN_VERSION }}
        fi
        sudo make install

    - name: Install Python dependencies
      run: |
        python -m pip install --upgrade pip
        python -m pip install --editable .[build]
        python -m pip install .[docs]
        # Remove the version of breathe that is automatically installed by the previous commands
        # as it confuses the build. This build should pick up breathe from the repo source
        python -m pip uninstall --yes breathe

    - name: Build the documentation
      run: |
        make parser
        make html
        rm documentation/build/html/.buildinfo

    - uses: actions/upload-artifact@v4
      with:
        name: docs build artifacts
        path: |
          documentation/build/html
          examples/*/*/xml
