docs.yaml

name: Build/Deploy Docs
on:
  workflow_call:
    inputs:
      target_ref:
        required: false
        type: string
  workflow_dispatch:
    inputs:
      target_ref:
        description: 'Commit or branch to build docs'
        default: 'main'
        required: false
        type: string

jobs:
  read-params:
    name: Get branch or commit ID
    runs-on: ubuntu-latest
    outputs:
      target_ref: ${{ env.target_ref }}
    steps:
    - name: Set target ref automatically
      if: inputs.target_ref == ''
      run: |
        echo "target_ref=${{ github.head_ref || github.ref_name }}" >> $GITHUB_ENV
    - name: Read target ref from inputs
      if: inputs.target_ref
      run: |
        echo 'target_ref=${{ inputs.target_ref }}' >> $GITHUB_ENV
  docs-build:
    name: Build documentation
    runs-on: ubuntu-latest
    needs: read-params
    permissions:
      contents: read
      pages: write
      actions: read
      id-token: write
      checks: write
    steps:
      - name: Check ref
        run: echo "target_ref=${{ needs.read-params.outputs.target_ref }}" >> $GITHUB_ENV
      - name: Add GLMakie/XFVB dependencies
        run: sudo apt-get update && sudo apt-get install -y xorg-dev mesa-utils xvfb libgl1 freeglut3-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
      - uses: actions/checkout@v4
        with:
          ref: ${{ env.target_ref }}
          submodules: recursive
      - uses: julia-actions/setup-julia@v2
        with:
          version: '1'
      - uses: julia-actions/cache@v2
      - name: Setup LCOV
        run: (command -V genhtml || sudo apt-get -y install lcov) && genhtml --version
        continue-on-error: true
      - name: Configure doc environment
        run: make docsetup
      - uses: julia-actions/julia-buildpkg@v1
      - uses: actions/download-artifact@v4
        continue-on-error: true
        with:
          pattern: 'coverage-*.info'
          path: coverage
      - name: Display structure of downloaded files
        run: ls -R
      - name: Combine LCOV files and generate coverage html
        continue-on-error: true
        run: |
          lcov $(find coverage -name 'coverage-lcov.info' -printf '-a %p ') -o coverage-lcov.info
          test -f coverage-lcov.info && make coverage-lcov -o '*/*.cov'
      - name: Display structure of whatever just happened
        run: ls -R
      - name: Build docs
        run: make DOC_PREFIX='xvfb-run -a' doc -o '*/*.cov'
      - name: Display structure of docs
        run: ls -R docs
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload report Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: "./docs/build"
  docs-deploy:
    name: Deploy documentation
    if:  needs.read-params.outputs.target_ref == 'main'
    needs: [read-params, docs-build]
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      actions: read
      id-token: write
      checks: write
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        continue-on-error: true