ci-docs.yml

name: CI Docs

on:
  workflow_call:
  workflow_dispatch:

# We set `concurrency` to prevent having this workflow being run on code that is not up-to-date on a PR (a user make multiple push in a quick manner).
# But on the main branch, we don't want that behavior.
# Having the workflow run on each merge commit is something we would like, that could help us where a regression was made and missed by previous checks.
#
# For that we use `head_ref` that is only defined on `pull-request` and fallback to `run_id` (this is a counter, so it's value is unique between workflow call).
concurrency:
  group: ci-docs-${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

env:
  poetry-version: 1.5.1
  # Convert sphinx warning into errors.
  SPHINXOPTS: --fail-on-warning --verbose

permissions:
  contents: read

jobs:
  docs:
    name: Build & Check documentations
    runs-on: ubuntu-22.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin v4.2.2
        with:
          sparse-checkout: |
            .github
            HISTORY.rst
            docs
        timeout-minutes: 2

      - uses: ./.github/actions/setup-python-poetry
        id: setup-python
        with:
          poetry-version: ${{ env.poetry-version }}
          project-path: ./docs
        timeout-minutes: 10

      - name: Install gettext (required by powrap)
        run: sudo apt-get install -y gettext
        timeout-minutes: 5

      - name: Install docs deps
        run: |
          poetry --directory ./docs env info
          poetry --directory ./docs install
        timeout-minutes: 5

      - name: Update translation
        run: poetry run make --environment-overrides intl-fr
        working-directory: docs
        timeout-minutes: 2

      - name: Wrap `*.po` files
        run: poetry run make --environment-overrides wrap
        working-directory: docs
        timeout-minutes: 1

      - name: Check if `*.po` were modified
        shell: bash
        run: |
          if git status --porcelain | grep '**.po'; then
            # PO files were modified, the step fail
            exit 1
          else
            # NO PO files were modified, the step succeed
            exit 0
          fi

      - name: Build html documentation
        run: poetry run make --environment-overrides html
        working-directory: docs
        timeout-minutes: 2