docs.yml

name: Build and Deploy Documentation

on:
  # Runs on pushes targeting the default branch (main or master)
  push:
    branches: ["main", "master"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job for GitHub
  build-github:
    runs-on: ubuntu-latest
    if: ${{ github.server_url == 'https://github.com' }}
    # Set ENV vars at the job level to be inherited by all steps, including actions
    env:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/ca-certificates.crt
      SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt
      REQUESTS_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt
      # Use CPU-only PyTorch to save disk space
      PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
      TORCH_CPU_ONLY: "true"

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      # Install Act dependencies FIRST (before any apt-get commands)
      - name: Install Act dependencies
        if: ${{ env.ACT }}
        run: |
          # Ensure apt-get is available and install sudo for 'act' environments
          if ! command -v apt-get &> /dev/null; then
            echo "apt-get not found, cannot proceed"
            exit 1
          fi
          # Install apt-utils first to avoid debconf warnings, then sudo
          DEBIAN_FRONTEND=noninteractive apt-get update && \
          DEBIAN_FRONTEND=noninteractive apt-get install -y apt-utils sudo

      - name: Install Runner Dependencies & Configure CA
        run: |
          sudo apt-get update
          # Install lsb-release, Node.js, and ca-certificates all at once
          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y lsb-release nodejs ca-certificates default-jre build-essential

          # Trust your mounted certificate (from the act command)
          sudo update-ca-certificates

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12.3'
          cache: 'pip'

      - name: Install dependencies
        run: |
          # Ensure setuptools and wheel are present before installing the project
          pip install --upgrade pip setuptools wheel
          # psutil/ipython required for imports during autodoc (H2OBaseClassifier, pipeline.data)
          # torch is needed for some model classes that are imported during autodoc
          pip install torch
          pip install psutil ipython
          pip install .[docs]

      - name: Verify PyTorch installation
        run: |
          python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"

      - name: Build documentation
        run: sphinx-build -b html -D html_baseurl="" docs/source docs/build

      - name: Upload artifact for GitHub Pages
        if: ${{ !env.ACT }}
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs/build

      - name: Upload artifact for GitHub
        uses: actions/upload-artifact@v4
        with:
          name: docs-artifact
          path: ./docs/build

  # Build job for Gitea
  build-gitea:
    runs-on: ubuntu-latest
    if: ${{ github.server_url != 'https://github.com' }}
    env:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/ca-certificates.crt
      SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt
      REQUESTS_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt
      PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
      TORCH_CPU_ONLY: "true"

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Act dependencies
        if: ${{ env.ACT }}
        run: |
          if ! command -v apt-get &> /dev/null; then
            echo "apt-get not found, cannot proceed"
            exit 1
          fi
          DEBIAN_FRONTEND=noninteractive apt-get update && \
          DEBIAN_FRONTEND=noninteractive apt-get install -y apt-utils sudo

      - name: Install Runner Dependencies & Configure CA
        run: |
          sudo apt-get update
          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y lsb-release nodejs ca-certificates default-jre build-essential
          sudo update-ca-certificates

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12.3'
          cache: 'pip'

      - name: Install dependencies
        run: |
          pip install --upgrade pip setuptools wheel
          # psutil/ipython required for imports during autodoc (H2OBaseClassifier, pipeline.data)
          # torch is needed for some model classes that are imported during autodoc
          pip install torch
          pip install psutil ipython
          pip install .[docs]

      - name: Verify PyTorch installation
        run: |
          python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"

      - name: Build documentation
        run: sphinx-build -b html -D html_baseurl="" docs/source docs/build

      - name: Upload artifact for Gitea
        uses: actions/upload-artifact@v3
        with:
          name: docs-artifact
          path: ./docs/build

  # Deploy job for GitHub Pages
  deploy-github:
    needs: build-github
    if: ${{ github.server_url == 'https://github.com' }}
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    env:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/ca-certificates.crt

    steps:
      - name: Install Act dependencies
        if: ${{ env.ACT }}
        run: |
          apt-get update && apt-get install -y sudo

      - name: Install Runner Dependencies & Configure CA
        run: |
          sudo apt-get update
          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs ca-certificates
          sudo update-ca-certificates

      - name: Deploy to GitHub Pages
        id: deployment
        if: ${{ !env.ACT }}
        uses: actions/deploy-pages@v4

  # Deploy job for Gitea
  deploy-gitea:
    needs: build-gitea
    if: ${{ github.server_url != 'https://github.com' }}
    runs-on: ubuntu-latest
    env:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/ca-certificates.crt

    steps:
      - name: Install Act dependencies
        if: ${{ env.ACT }}
        run: |
          apt-get update && apt-get install -y sudo

      - name: Install Runner Dependencies & Configure CA
        run: |
          sudo apt-get update
          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs ca-certificates
          sudo update-ca-certificates

      - name: Download artifact
        # Use a GHES-compatible version of download-artifact
        uses: actions/download-artifact@v3
        with:
          name: docs-artifact
          path: ./docs-site

      - name: Deploy to Gitea docs location
        run: |
          echo "Deploying documentation to Gitea's special directory..."
          # upload-artifact@v3 does not create a tarball, so no extraction is needed.
          # The '/pages' directory is a mounted volume on the Gitea runner for serving static content.
          # Deploy to a subfolder named after the repository
          TARGET_DIR="/pages/docs/${{ github.event.repository.name }}"

          # Clean, recreate, copy, and set permissions
          sudo rm -rf "$TARGET_DIR"
          sudo mkdir -p "$TARGET_DIR"
          sudo cp -r ./docs-site/. "$TARGET_DIR/"
          sudo chmod -R 755 "$TARGET_DIR"