docs.yml

# .github/workflows/docs.yml
name: Build and Deploy Docs

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job for GitHub
  build-github:
    name: Build Documentation (GitHub)
    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

    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
          sudo update-ca-certificates

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

      - name: Install dependencies
        run: |
          pip install --upgrade pip setuptools wheel
          pip install -e ".[dev]"

      - name: Build Sphinx documentation
        run: sphinx-build -b html docs/source docs/build/html

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

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

  # Build job for Gitea
  build-gitea:
    name: Build Documentation (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

    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
          sudo update-ca-certificates

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

      - name: Install dependencies
        run: |
          pip install --upgrade pip setuptools wheel
          pip install -e ".[dev]"

      - name: Build Sphinx documentation
        run: sphinx-build -b html docs/source docs/build/html

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

  # Deploy job for GitHub Pages
  deploy-github:
    name: Deploy to GitHub Pages
    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:
    name: Deploy to Gitea Pages
    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
        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..."
          # 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"