api_documentation.yml

on:
  push:
    paths:
      - '.github/workflows/api_documentation.yml' # Run when this workflow changes
      - '**/src/**'
  workflow_dispatch: # Run when manually triggered
  workflow_call: # Run when called by another workflow

name: 📜 API Documentation Workflow

jobs:
  build_documentation_job:
    name: 🛠 Build Documentation Job
    if: |
      (
        github.event_name == 'push' 
        && github.ref == 'refs/heads/main'
      ) || (
        !startsWith(github.event.head_commit.message, 'style:')
        && !startsWith(github.event.head_commit.message, 'style(')
        && !startsWith(github.event.head_commit.message, 'chore:')
        && !startsWith(github.event.head_commit.message, 'chore(')
      )
    strategy:
      fail-fast: true
      matrix:
        platform: [linux]
        cpu_architecture: [x86_64]
        include:
          - platform: linux
            cicd_runner: ubuntu-latest
          - compilation_target: x86_64-unknown-linux-gnu
            cpu_architecture: x86_64
            platform: linux
            toolchain: gnu
    runs-on: ${{ matrix.cicd_runner }}
    steps:
      - name: 🎟 Checkout Git Repository Step
        id: repository_checkout_step
        uses: actions/checkout@v4
      - name: ↕️ Install Ubuntu Dependencies
        id: dependencies_install_step
        if: ${{ matrix.cicd_runner == 'ubuntu-latest' }}
        uses: awalsh128/cache-apt-pkgs-action@latest
        with:
          packages: libgtk-4-dev
          version: 1.0
      - name: 🧰 Install Rust Toolchain
        id: toolchain_install_step
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: nightly
          targets: ${{ matrix.compilation_target }}          
          components: rustc, cargo
      - name: 🔄 Install Cross-Compilation Tools
        id: cross_install_step
        if: ${{ matrix.cpu_architecture != 'x86_64' }}
        uses: taiki-e/setup-cross-toolchain-action@v1
        with:
          targets: ${{ matrix.compilation_target }}          
      - name: 🗂 Setup Cache
        id: cache_setup_step
        uses: Swatinem/rust-cache@v2
      - name: 📜 Cargo Doc
        id: cargo_doc_step
        env:
          RUSTDOCFLAGS: "--enable-index-page -Zunstable-options"
        run: |
          cargo doc --all-features --workspace --no-deps --document-private-items
      - name: ⬆ Upload Docs Artifact
        id: documentation_upload_step        
        uses: actions/upload-pages-artifact@v3
        with: 
          path: target/doc
  publish_documentation_job:
    name: ✈ Publish Documentation Job   
    needs: build_documentation_job
    runs-on: ubuntu-latest
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source
    concurrency:
      group: "pages"
      cancel-in-progress: true
    environment:
      name: github-pages
      url: ${{ steps.deployment_step.outputs.page_url }}      
    steps:
      - name: ✈ Deploy to GitHub Pages
        id: deployment_step
        uses: actions/deploy-pages@v4