doc.yml

name: AUTO doc
concurrency:
  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
  cancel-in-progress: true
on:
  pull_request:
  push:
    branches: [dev, stable]
  workflow_dispatch:

jobs:
  build:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    permissions:
      contents: write
    defaults:
      run:
        shell: bash
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          path: src
      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: '3.12'
      - name: Build doc
        env:
          PYTHONPATH: ${{ env.PYTHONPATH != '' && format( '{1}:src', env.PYTHONPATH ) || 'src' }}
          TZ: UTC
        run: |
          uv run --project src --extra doc sphinx-build -WT --keep-going -j auto src/doc doc-build
      - name: Upload documentation
        uses: actions/upload-artifact@v7
        with:
          name: doc
          path: |
            doc-build
            !doc-build/.doctrees

      # deploy
      - name: Deploy the {dev,stable} documentation to github.io
        # only on push to dev or stable
        if: ${{ success() && github.event_name == 'push' && contains(fromJSON('["dev", "stable"]'), github.ref_name) }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: doc-build
          exclude_assets: '.doctrees'
          # destination_dir: github.ref_name will be dev or stable
          destination_dir: ${{ github.ref_name }}
          user_name: 'github-doc-action[bot]'
          user_email: 'github-doc-action[bot]@users.noreply.github.com'