docs-build-update.yml

name: Build & update docs

on:
  push:
    branches: [ 'doc/*', 'docs/*', master, "maint/*" ]
    tags: [ '*' ]
  pull_request:
    branches: [ master, 'maint/*' ]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    if: ${{ github.event_name != 'pull_request' || !contains(github.event.head_commit.message, '[skip ci]') }}
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
      with:
        ssh-key: "${{ secrets.NIPREPS_DEPLOY }}"
        fetch-depth: 0

    - name: Determine current branch/tag name & set-up git author
      run: |
        if [[ "$GITHUB_REF" == refs/tags/* ]]; then
          CURBRANCH=${GITHUB_REF##*/}
        elif [[ "$GITHUB_REF" == refs/pull/* ]]; then
          CURBRANCH=${GITHUB_REF%/*}
          CURBRANCH=${CURBRANCH##*/}
        elif [[ "$GITHUB_REF" == refs/heads/* ]]; then
          CURBRANCH=${GITHUB_REF##*/}
        fi

        # Remove forward slashes
        CURBRANCH=$( echo $CURBRANCH | sed 's+/+_+g' )
        echo "Building branch/tag ${CURBRANCH:-<unkwown>}, from git ref <$GITHUB_REF>"
        echo "CURBRANCH=${CURBRANCH}" >> ${GITHUB_ENV}

        # Pacify git if we were to commit something
        git config user.email "nipreps@gmail.com"
        git config user.name "NiPreps Bot"

    - name: Install GraphViz & pandoc
      run: |
        sudo apt-get update -y
        sudo apt-get install -y --no-install-recommends graphviz pandoc texlive

    - name: Set up Python 3
      uses: actions/setup-python@v5
      with:
        python-version: 3

    - name: Install dependencies
      run: |
        python -m pip install -U build hatch hatchling pip docutils
        python -m pip install -r docs/requirements.txt
        python -m hatch version | tail -n1 | xargs

    - name: Pre-install template
      run: |
        python -c "from templateflow.api import get; get('MNI152NLin2009cAsym', desc='brain', resolution=1, suffix='T1w')"

    - name: Build docs
      run: |
          make -C docs/ SPHINXOPTS="-W" BUILDDIR="$HOME/docs" OUTDIR="${CURBRANCH:-html}" html

    - name: Push created tag to gh-pages
      if: startsWith(github.ref, 'refs/tags/')
      run: |
        MAJOR_MINOR=${CURBRANCH%.*}
        if [[ "${MAJOR_MINOR}" == "" ]]; then
            echo "Could not identify release series"
            exit 1
        fi
        git checkout -b gh-pages origin/gh-pages
        git rm -r ${MAJOR_MINOR}/ || true
        # It is fundamental that the directory does not exist at all.
        rm -rf ${MAJOR_MINOR}
        cp -r $HOME/docs/$CURBRANCH $PWD/${MAJOR_MINOR}
        git add ${MAJOR_MINOR}
        python -c "from pathlib import Path; import json; f=Path('versions.json'); d=json.loads(f.read_text()); d['tags'].append(\"${MAJOR_MINOR}\"); d['tags'] = list(sorted(set(d['tags']))); f.write_text(json.dumps(d, indent=4)); print('Updated versions.json')"
        git add versions.json
        git commit -m "rel(${CURBRANCH}): Update docs of ${MAJOR_MINOR} series" || true
        git push

    - name: Push "master" docs to gh-pages after a push to master (typically, a PR merge).
      if: github.ref == 'refs/heads/master'
      run: |
        if [[ "${CURBRANCH}" != "master" ]]; then
            echo "$CURBRANCH is not the default development branch"
            exit 1
        fi
        git checkout -b gh-pages origin/gh-pages
        git rm -r master/ || true
        # It is fundamental that the directory does not exist at all.
        rm -rf master
        cp -r $HOME/docs/$CURBRANCH $PWD/master
        git add master
        git commit -am "docs(master): Update docs of development line" || true
        git push