name: Documentation

on:
  push:
    branches:
      - feature-46
    paths:
      - 'docs/**'
      - 'release_notes/**'
      - '.forgejo/workflows/docs.yml'
  workflow_dispatch:

# Deux publications simultanées se pousseraient l'une sur l'autre : la branche
# pages est écrasée à chaque fois, le dernier arrivé gagnerait au hasard.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  publish:
    runs-on: docker
    env:
      TOKEN: ${{ secrets.RELEASE }}
      SITE_DIR: /tmp/site
    steps:
      - uses: actions/checkout@v3

      - name: Installer Sphinx
        run: |
          apt-get update
          apt-get install -y python3 python3-venv git
          python3 -m venv /tmp/venv
          /tmp/venv/bin/pip install --quiet --upgrade pip
          /tmp/venv/bin/pip install --quiet -r docs/requirements.txt

      # -W --keep-going : une référence croisée cassée doit arrêter la
      # publication, pas produire un site avec des liens morts. --keep-going
      # affiche tous les avertissements avant d'échouer, plutôt que le premier.
      # -d place le cache de Sphinx hors du site : sans lui, .doctrees — près
      # d'un mégaoctet d'état interne — se retrouve publié à la racine.
      - name: Construire la documentation
        run: |
          /tmp/venv/bin/sphinx-build -b html -W --keep-going \
            -d /tmp/doctrees docs "${SITE_DIR}"

      - name: Alléger le site
        run: |
          # Source maps du thème : ~3 Mo de fichiers que seuls les outils de
          # développement du navigateur vont chercher, jamais une page servie.
          find "${SITE_DIR}" -name '*.map' -delete
          rm -f "${SITE_DIR}/.buildinfo"
          # Neutralise Jekyll si le serveur de pages l'applique : Sphinx écrit
          # _static/ et _sources/, que Jekyll ignore silencieusement.
          touch "${SITE_DIR}/.nojekyll"
          du -sh "${SITE_DIR}"

      # La branche pages ne contient que le site, à la racine. Le build est
      # greffé sur l'historique existant plutôt que poussé en force : un push
      # en avance rapide ne demande que le droit d'écrire sur la branche, là
      # où le force-push exige une dérogation supplémentaire dans la
      # protection de branche.
      - name: Publier sur la branche pages
        run: |
          cd "${SITE_DIR}"
          git init --quiet --initial-branch=pages
          git config user.name "forgejo-actions"
          git config user.email "forgejo-actions@git.g3e.fr"
          git remote add origin "https://${TOKEN}@git.g3e.fr/${{ github.repository }}.git"

          # --depth=1 : seul le dernier commit sert de parent, l'historique
          # complet du site n'a pas à être rapatrié à chaque build.
          if git fetch --quiet --depth=1 origin pages 2>/dev/null
          then
            git reset --soft FETCH_HEAD
          else
            echo "branche pages absente : premier build"
          fi

          git add -A
          if git diff --cached --quiet
          then
            echo "site identique au précédent, rien à publier"
            exit 0
          fi

          git commit --quiet -m "docs: build de ${GITHUB_SHA}"
          git push --quiet origin pages
          echo "publié : $(git rev-parse --short HEAD) — $(git ls-files | wc -l) fichiers"