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, en un seul
      # commit sans histoire : ce sont des artefacts reconstructibles, et
      # l'historique de main suffit à savoir d'où ils viennent.
      - 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 add -A
          git commit --quiet -m "docs: build de ${GITHUB_SHA}"
          git push --force --quiet \
            "https://${TOKEN}@git.g3e.fr/${{ github.repository }}.git" pages
          echo "publié : $(git rev-parse --short HEAD) — $(git ls-files | wc -l) fichiers"