gh_pages_doc.yml

name: Build and Deploy docs to GH pages

on:
  push:
    branches:
      - master
    tags:
      - "v*"
  pull_request:
    branches: ["master"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -el {0}
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Fetch all history for all branches and tags

      - name: Set up Miniconda
        uses: conda-incubator/setup-miniconda@v3
        with:
          miniforge-version: latest
          python-version: 3.12 # Specify the Python version compatible with your environment
          environment-file: docs/environment.yml # Use your environment.yml to install dependencies
          activate-environment: readthedocs # Name from environment.yml
          auto-activate-base: false
      - name: Determine build context
        id: context
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "Build context: PR"
            echo "build_context=pr" >> $GITHUB_ENV
          elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
            echo "Build context: Tag"
            echo "build_context=tag" >> $GITHUB_ENV
          else
            echo "Build context: Master"
            echo "build_context=master" >> $GITHUB_ENV
          fi

      - name: Check if tagged version already exists on gh-pages
        if: env.build_context == 'master'
        id: check_exists
        run: |
          git fetch origin gh-pages
          version=$(git tag --sort=-v:refname | head -n 1)
          echo "Checking if version $version exists..."
          if git ls-tree --name-only origin/gh-pages | grep -q "^$version/"; then
            echo "Version $version exists."
            echo "exists=true" >> $GITHUB_ENV
          else
            echo "No existing build for $version."
            echo "exists=false" >> $GITHUB_ENV
          fi

      - name: Build documentation for PR
        if: env.build_context == 'pr'
        run: |
          sphinx-build -E docs/source _build/html

      - name: Build all tagged versions for master push
        if: env.build_context == 'master' && env.exists == 'false'
        run: |
          sphinx-multiversion docs/source _build/html

      - name: Build tag version for tag push
        if: env.build_context == 'tag'
        run: |
          sphinx-multiversion docs/source _build/html --tag ${{ github.ref_name }}

      - name: Deploy to gh-pages
        if: env.build_context != 'pr'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/html
          keep_files: true

      - name: Deploy PR preview to a subfolder in gh-pages
        if: env.build_context == 'pr'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/html
          publish_branch: gh-pages
          destination_dir: pr-${{ github.event.pull_request.number }}
          keep_files: true