pages.yml

# ============================================================================
# Build & deploy the DataLab documentation to GitHub Pages.
#
# Mirrors the local VS Code tasks `GitHub Pages: build` + `GitHub Pages:
# upload` (see scripts/build_ghpages.bat + scripts/upload_ghpages.bat).
#
# Triggers:
#   * workflow_dispatch  - manual run
#   * workflow_call      - invoked by `release.yml` after a successful release
#
# Deployment target:
#   The current upload script pushes to the external repository
#   `DataLab-Platform/DataLab-Platform.github.io`. To keep parity, this
#   workflow pushes to the same repo using `peaceiris/actions-gh-pages`.
#   It requires the repository secret `GH_PAGES_TOKEN` (a fine-grained PAT
#   with write access to that external repo) OR `GH_PAGES_DEPLOY_KEY`
#   (an SSH deploy key configured on the external repo). At least one of
#   the two must be defined.
# ============================================================================
name: Build & Deploy Documentation

on:
  workflow_dispatch:
    inputs:
      deploy:
        description: "Push the result to DataLab-Platform.github.io"
        required: true
        type: boolean
        default: true
  workflow_call:
    inputs:
      deploy:
        description: "Push the result to DataLab-Platform.github.io"
        required: false
        type: boolean
        default: true
    secrets:
      GH_PAGES_TOKEN:
        required: false
      GH_PAGES_DEPLOY_KEY:
        required: false

permissions:
  contents: read

concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DISPLAY: ":99.0"
      QT_COLOR_MODE: light
      RELEASE: "1"
      UNATTENDED: "1"
    steps:
      - uses: actions/checkout@v4

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

      - name: Install system dependencies (Qt + Xvfb)
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
            libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 \
            x11-utils xvfb
          /sbin/start-stop-daemon --start --quiet \
            --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background \
            --exec /usr/bin/Xvfb -- :99 -screen 0 1920x1200x24 -ac +extension GLX

      - name: Install Python dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install --upgrade PythonQwt guidata PlotPy Sigima
          python -m pip install .[doc,qt]
          # sigima.proc.validation imports `_pytest` at module level (tech
          # debt); doc/update_validation_status.py needs it to be importable.
          python -m pip install pytest

      - name: Symlink Sigima sibling checkout for doc literalincludes
        run: |
          SITE=$(python -c "import sigima, os; print(os.path.dirname(os.path.dirname(sigima.__file__)))")
          ln -snf "$SITE" "$GITHUB_WORKSPACE/../Sigima"

      - name: Compile translations (UI + docs)
        run: |
          python -m sphinx build doc build/gettext -b gettext -W
          python -m sphinx_intl build -d doc/locale
          python -m guidata.utils.translations compile --name datalab --directory .

      - name: Generate doc assets
        run: |
          python -m guidata.utils.genreqs all
          python doc/update_validation_status.py

      - name: Build HTML documentation (fr + en)
        # NOTE: doc/update_screenshots.py is intentionally NOT run here —
        # screenshots in doc/images/ are committed assets (refreshed locally
        # by the maintainer via scripts/update_screenshots.bat). Sphinx
        # picks `foo.<lang>.png` automatically when present (via
        # `figure_language_filename` in doc/conf.py) and falls back to the
        # unsuffixed `foo.png` otherwise. See _build.yml for the same
        # rationale.
        run: |
          mkdir -p site
          # Loop variable is `LNG`, not `LANG`: `LANG` is the OS locale env var
          # read by Python's `locale.setlocale`, and setting it to a bare "fr"
          # / "en" makes Sphinx fail with `locale.Error: unsupported locale
          # setting` (see _build.yml for the same workaround).
          for LNG in fr en; do
            python -m sphinx -b html -D language=$LNG doc "site/$LNG"
          done
          # Top-level index redirecting to the English version.
          cat > site/index.html <<'EOF'
          <!doctype html>
          <meta http-equiv="refresh" content="0; url=./en/">
          <link rel="canonical" href="./en/">
          EOF

      - name: Upload built site as artifact
        uses: actions/upload-artifact@v4
        with:
          name: datalab-docs-html
          path: site/
          retention-days: 14

      - name: Check for deployment credentials
        id: creds
        if: ${{ inputs.deploy }}
        env:
          TOKEN: ${{ secrets.GH_PAGES_TOKEN }}
          KEY: ${{ secrets.GH_PAGES_DEPLOY_KEY }}
        run: |
          if [ -n "$TOKEN" ]; then
            echo "method=token" >> "$GITHUB_OUTPUT"
          elif [ -n "$KEY" ]; then
            echo "method=ssh" >> "$GITHUB_OUTPUT"
          else
            echo "::warning::No GH_PAGES_TOKEN or GH_PAGES_DEPLOY_KEY secret; skipping deployment."
            echo "method=none" >> "$GITHUB_OUTPUT"
          fi

      - name: Deploy to DataLab-Platform.github.io (via PAT)
        if: ${{ inputs.deploy && steps.creds.outputs.method == 'token' }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.GH_PAGES_TOKEN }}
          external_repository: DataLab-Platform/DataLab-Platform.github.io
          publish_branch: main
          publish_dir: ./site
          keep_files: false
          commit_message: "Update documentation from ${{ github.repository }}@${{ github.sha }}"

      - name: Deploy to DataLab-Platform.github.io (via SSH deploy key)
        if: ${{ inputs.deploy && steps.creds.outputs.method == 'ssh' }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          deploy_key: ${{ secrets.GH_PAGES_DEPLOY_KEY }}
          external_repository: DataLab-Platform/DataLab-Platform.github.io
          publish_branch: main
          publish_dir: ./site
          keep_files: false
          commit_message: "Update documentation from ${{ github.repository }}@${{ github.sha }}"