docs.yml

name: Docs

on:
  push:
    branches: [ master, develop, 'dev/*' ]
  pull_request:
    branches: [ master, develop ]

jobs:
  build:
    runs-on: ubuntu-22.04
    defaults:
      run:
        shell: bash -el {0}
    steps:
    - name: Checkout repo
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Set up conda env
      uses: ./.github/actions/setup-conda-env
      with:
        environment-file: environments/eeg-expy-docsbuild.yml
        activate-environment: eeg-expy-docsbuild

    - name: Get list of changed files
      id: changes
      run: |
        git fetch origin master
        git diff --name-only origin/master...HEAD > changed_files.txt
        cat changed_files.txt

    - name: Determine build mode
      id: mode
      run: |
        if grep -vqE '^examples/.*\.py$' changed_files.txt; then
          echo "FULL_BUILD=true" >> $GITHUB_ENV
          echo "Detected non-example file change. Full build triggered."
        else
          # || true prevents grep's exit code 1 (no matches) from aborting the step
          CHANGED_EXAMPLES=$(grep '^examples/.*\.py$' changed_files.txt | paste -sd '|' - || true)
          echo "FULL_BUILD=false" >> $GITHUB_ENV
          echo "CHANGED_EXAMPLES=$CHANGED_EXAMPLES" >> $GITHUB_ENV
          echo "Changed examples: $CHANGED_EXAMPLES"
        fi

    - name: Cache built documentation
      id: cache-docs
      uses: actions/cache@v4
      with:
        path: |
          doc/_build/html
        key: ${{ runner.os }}-sphinx-${{ hashFiles('examples/**/*.py', 'doc/**/*', 'conf.py') }}
        restore-keys: |
          ${{ runner.os }}-sphinx-

    - name: Build docs
      run: make docs

    - name: Deploy Docs
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/master'  # TODO: Deploy seperate develop-version of docs?
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: doc/_build/html