name: Lint Check

on:
  schedule:
    # After the 04:00 sync and 05:00 maintenance, so it lints tonight's result.
    # (Pushes made with GITHUB_TOKEN do not trigger this workflow.)
    - cron: '0 7 * * *'
  push:
    branches:
      - '**'   # '*' does not match branch names containing a slash
  pull_request:
    branches:
      - '*'
  workflow_dispatch:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout CPython docs
        uses: actions/checkout@v4
        with:
          repository: python/cpython
          ref: '3.15'

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'

      - name: Install sphinx-lint and polib
        run: pip install sphinx-lint polib

      - name: Install gettext tools
        run: sudo apt-get install -y gettext

      - name: Setup virtual environment
        run: make venv
        working-directory: ./Doc

      - name: Pin Sphinx to 9.1.0
        # make venv may resolve an older Sphinx via requirements.txt; pin
        # explicitly so we get the reordered-ref / translated-display-text
        # i18n fixes (sphinx-doc/sphinx#14144). Bump this once #14162 lands
        # upstream and re-check whether the suppression below is still needed.
        run: ./venv/bin/pip install "sphinx==9.1.0"
        working-directory: ./Doc

      - name: Checkout translation files
        uses: actions/checkout@v4
        with:
          path: Doc/locales/fa/LC_MESSAGES

      - name: Setup problem matcher
        uses: rffontenelle/sphinx-lint-problem-matcher@v1.0.0

      # we have to disable trailing-whitespace on sphinx-lint for now
      # see github.com/sphinx-contrib/sphinx-lint/issues/120
      - name: Run sphinx-lint
        run: sphinx-lint --disable trailing-whitespace
        working-directory: Doc/locales/fa/LC_MESSAGES

      - name: Check PO file validity
        run: find . -name '*.po' -print0 | xargs -0 -n1 msgfmt --check -o /dev/null
        working-directory: Doc/locales/fa/LC_MESSAGES

      - name: Check markup preservation
        run: python3 scripts/check_markup.py .
        working-directory: Doc/locales/fa/LC_MESSAGES

      - name: Build documentation
        # suppress_warnings for i18n.inconsistent_references: confirmed
        # upstream false positive for translated display text / custom
        # pending_xref directives (e.g. CPython's `.. availability::`),
        # tracked and still open at sphinx-doc/sphinx#14162.
        run: make -e SPHINXOPTS="--color -D language='fa' -D gettext_allow_fuzzy_translations=1 -D suppress_warnings=i18n.inconsistent_references -W --keep-going" html
        working-directory: ./Doc