pnl-ci-docs.yml

name: PsyNeuLink Docs CI

on:
  push:
    branches-ignore:
      - 'dependabot/**'
    tags:
      - 'v*'
  pull_request:

# run only the latest instance of this workflow job for the current branch/PR
# cancel older runs
# fall back to run id if not available (run id is unique -> no cancellations)
concurrency:
  group: ci-${{ github.ref || github.run_id }}-${{ github.workflow }}
  cancel-in-progress: true

jobs:
  docs-build:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12']
        os: [ubuntu-latest, macos-latest, windows-latest]
        pnl-version: ${{ (github.event_name == 'push') && fromJSON('["head"]') || fromJSON('["head", "base"]') }}
        exclude:
          - os: macos-latest
            pnl-version: 'base'
          - os: windows-latest
            pnl-version: 'base'
          - python-version: '3.7'
            pnl-version: 'base'
          - python-version: '3.8'
            pnl-version: 'base'
          - python-version: '3.9'
            pnl-version: 'base'
          - python-version: '3.10'
            pnl-version: 'base'
          - python-version: '3.12'
            pnl-version: 'base'

            # Python 3.7 x64 on macos-14 (arm64) images is broken [0]
            # and arm64 version is not available [1].
            # Restrict python 3.7 macos runs to macos-13
            # [0] https://github.com/actions/setup-python/issues/855
            # [1] https://github.com/actions/setup-python/issues/856
          - python-version: '3.7'
            os: macos-latest

    outputs:
      on_master: ${{ steps.on_master.outputs.on-branch }}

    steps:
    # Increased fetch-depth and tag checkout needed compared to pnl-ci.yml
    - name: Checkout sources
      uses: actions/checkout@v4
      if: ${{ matrix.pnl-version == 'head' }}
      with:
        fetch-depth: 200
        ref: ${{ github.ref }}

    - name: Checkout pull base
      uses: actions/checkout@v4
      if: ${{ matrix.pnl-version == 'base' }}
      with:
        fetch-depth: 200
        ref: ${{ github.base_ref }}

    - name: Checkout tags
      run: git fetch --tags origin master

    - name: Check if on master
      if: ${{ github.event_name == 'push' }}
      id: on_master
      uses: ./.github/actions/on-branch
      with:
        branch: master

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        # Block python3.7.17 on macos. see:
        # https://github.com/actions/setup-python/issues/682
        python-version: ${{ (matrix.os == 'macos-latest' && matrix.python-version == '3.7') && '3.7.16' || matrix.python-version }}

    - name: Get pip cache location
      shell: bash
      id: pip_cache
      run: |
        python -m pip install -U pip
        python -m pip --version
        echo "pip_cache_dir=$(python -m pip cache dir)" | tee -a $GITHUB_OUTPUT

    - name: Wheels cache
      uses: actions/cache@v4
      with:
        path: ${{ steps.pip_cache.outputs.pip_cache_dir }}/wheels
        key: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'doc_requirements.txt') }}-${{ github.sha }}
        restore-keys: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'doc_requirements.txt') }}

    # We need to install all PNL deps since docs config imports psyneulink module
    - name: Install PNL package
      uses: ./.github/actions/install-pnl
      with:
        features: 'doc'

    - name: Add git tag
      # The generated docs include PNL version,
      # set it to a fixed value to prevent polluting the diff
      # This needs to be done after installing PNL
      # to not interfere with dependency resolution
      id: add_zero_tag
      if: github.event_name == 'pull_request'
      run: git tag --force 'v0.0.0.0'

    - name: Build Documentation
      run: make -C docs/ html -e SPHINXOPTS="-aE -j auto"

    - name: Remove git tag
      # The generated docs include PNL version,
      # A special tag was set to a fixed value
      # to prevent polluting the diff
      if: steps.add_zero_tag.outcome != 'skipped'
      run: git tag -d 'v0.0.0.0'

    - name: Upload Documentation
      uses: actions/upload-artifact@v4
      with:
        name: Documentation-${{matrix.pnl-version}}-${{ matrix.os }}-${{ matrix.python-version }}
        retention-days: 1
        path: docs/build/html

    - name: Store PR number
      # The 'base' variant runs only on pull requests and has only one job
      if: ${{ matrix.pnl-version == 'base' }}
      run: echo ${{ github.event.pull_request.number }} > ./pr_number.txt

    - name: Upload PR number for other workflows
      # The 'base' variant runs only on pull requests and has only one job
      if: ${{ matrix.pnl-version == 'base' }}
      uses: actions/upload-artifact@v4
      with:
          name: pr_number
          path: ./pr_number.txt


  docs-deploy:
    strategy:
      fail-fast: false
      matrix:
        python-version: [3.11]
        os: [ubuntu-latest]

    runs-on: ${{ matrix.os }}
    permissions:
      contents: write
    needs: [docs-build]
    environment: github-pages
    if: github.event_name == 'push' &&
        (github.ref == 'refs/heads/master' ||
         github.ref == 'refs/heads/devel' ||
         github.ref == 'refs/heads/docs' ||
         (startsWith(github.ref, 'refs/tags/') && contains(needs.*.outputs.on_master, 'master'))
        )

    steps:
    - name: Checkout docs
      uses: actions/checkout@v4
      with:
        ref: gh-pages

    - name: Download branch docs
      uses: actions/download-artifact@v4
      with:
        name: Documentation-head-${{ matrix.os }}-${{ matrix.python-version }}
        path: _built_docs/${{ github.ref }}
      if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/devel' || github.ref == 'refs/heads/docs'

    - name: Update branch docs
      shell: bash
      run: |
        mkdir -p branch
        rm -rf "branch/${GITHUB_REF##*/}"
        # Remove '.doctrees' and move to correct location
        rm -rf "_built_docs/${GITHUB_REF}/.doctrees"
        mv -f "_built_docs/${GITHUB_REF}" branch/
      if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/devel' || github.ref == 'refs/heads/docs'

    - name: Download main docs
      uses: actions/download-artifact@v4
      with:
        name: Documentation-head-${{ matrix.os }}-${{ matrix.python-version }}
        # This overwrites files in current directory
      if: startsWith(github.ref, 'refs/tags/') && contains(needs.*.outputs.on_master, 'master')

    - name: Update main docs
      shell: bash
      run: |
        # Remove '.doctrees'
        rm -rf ".doctrees"
      if: startsWith(github.ref, 'refs/tags/') && contains(needs.*.outputs.on_master, 'master')

    - name: Commit docs changes
      shell: bash
      run: |
        # Commit changes to git
        git add .
        git config user.name "Documentation Bot"
        git config user.email "doc-bot@psyneulink.princeton.edu"
        git commit -m "Docs changes for $GITHUB_REF $GITHUB_SHA"
        git push