build_docs.yaml

name: Build of html documentation

# will run in root folder devops/devops/
# and we will create the following (which will persist until next run):
# - ./docs/python #executable
# - psychopy #repo
# - devops #repo

on:
  workflow_dispatch:  # manual
    inputs:
      pp_branch:
        description: 'PsychoPy branch to build docs from'
        required: true
        default: 'release'
        type: choice
        options:
          - dev
          - release
  pull_request:
    branches: [release, dev]
  push:
    branches: [release]

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:

  build:

    runs-on: [windows-latest]
    defaults:
      run:
        shell: bash
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10"]

    steps:
    - name: "SETUP: Configure Pages"
      id: pages
      uses: actions/configure-pages@v5
    - name: "SETUP: Checkout psychopy-docs"
      uses: actions/checkout@v4
      with:
        repository: psychopy/psychopy-docs
        ref: ${{ env.BRANCH }}
    - name: "SETUP: Checkout psychopy"
      uses: actions/checkout@v4
      with:
        repository: psychopy/psychopy
        path: psychopy
        ref: ${{ env.BRANCH }}
    - uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    - name: "SETUP: Install UV"
      uses: astral-sh/setup-uv@v7
      with:
        activate-environment: true
    - name: "SETUP: Select branch"
      run: |
        if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
          echo "Manual trigger for branch: ${{ github.event.inputs.pp_branch }}"
          branch="${{ github.event.inputs.pp_branch }}"
        else
          echo "Scheduled trigger, using release branch"
          branch="release"
        fi
        # export for other steps
        echo "BRANCH=$branch" >> $GITHUB_ENV
    - name: "SETUP: Install psychopy and dependencies"
      run: |
        ls
        # workaround for dukpy
        uv pip install git+https://gitlab.com/peircej/metapensiero.pj.git # includes fixes since last release
        # install psychopy depends for docs (incl sphinx extensions)
        uv pip install -e ".[tests]" ".[plugins]" --upgrade
    - name : "SETUP: Update alerts"
      run: |
        echo "\n Create Alerts documentation:"
        python updateAlerts_rst.py

    - name: "HTML: Sphinx build html"
      run: |
        sphinx-build -b html source build/html
    - name: "PDF: Sphinx build latex"
      run: |
        sphinx-build -b latex source build/latex
    # - name: "PDF: Cache Tectonic files"
    #   uses: actions/cache@v5
    #   with:
    #     path: ~/.cache/Tectonic
    #     key: ${{ runner.os }}-tectonic-${{ hashFiles('**/*.tex') }}
    #     restore-keys: |
    #       ${{ runner.os }}-tectonic-
    - name: "PDF: Set up Tectonic"
      uses: wtfjoke/setup-tectonic@v4
    - name: "PDF: Build PDF with Tectonic"
      run: |
        # try building with tectonic or fetch from psychopy.org if that fails (e.g. due to missing latex packages)
        if ! tectonic build/latex/PsychoPyManual.tex --outdir build/html; then
          echo "Tectonic build failed, fetching pre-built PDF from psychopy.org"
          curl -L -o build/html/PsychoPyManual.pdf https://www.psychopy.org/PsychoPyManual.pdf
        fi
    - name: fetch plugins.json
      run: |
        curl -LO https://github.com/psychopy/plugins/raw/refs/heads/main/plugins.json
        mv plugins.json build/html
    - name: add .nojekyll to docs folder so Actions doesn't rebuild with jekyll
      working-directory: build/html
      run: |
        touch .nojekyll
    - name: "DEBUG: Upload docs as artifact"
      uses: actions/upload-artifact@v6
      with:
        name: psychopy-docs
        path: build/html
    - name: "DEBUG: Upload PsychoPyManual.tex as artifact"
      uses: actions/upload-artifact@v6
      if: always() # upload even if build fails, to allow debugging of build issues
      with:
        name: PsychoPyManual.tex
        path: build/latex/PsychoPyManual.tex
    # upload as artefact for deployment job
    - name: Upload static files as artifact
      if: github.ref_name == 'release' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
      id: deployment
      uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action
      with:
        path: build/html/

  # Deployment job converts the artifact into a GitHub Pages deployment
  deploy:
    if: github.ref_name == 'release' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
    permissions:
      contents: write
      pages: write       # Added for GitHub Pages deployment
      id-token: write    # Necessary for actions/deploy-pages
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4