doc_checks.yml

name: Docs

on:
    push:
        branches-ignore:
            - 'backport**'
            - 'dependabot**'
    pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  docs:
    name: Documentation checks

    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
    container: ubuntu:24.04

    steps:
    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
    - name: Setup environment
      shell: bash -l {0}
      env:
        DEBIAN_FRONTEND: noninteractive
      run: |
          apt update
          apt install -y g++ cmake doxygen enchant-2 python3 python3-dev python3-pip python3-venv libproj-dev swig
          python3 -m venv create doc_env
          . doc_env/bin/activate
          python3 -m pip install -r doc/requirements.txt
          echo PATH=$PATH >> $GITHUB_ENV

    - name: Build GDAL
      shell: bash -l {0}
      run: |
          mkdir build
          cd build
          cmake .. \
            -DCMAKE_BUILD_TYPE=Debug \
            -DBUILD_APPS=ON \
            -DBUILD_DOCS=ON \
            -DBUILD_TESTING=ON \
            -DDOXYGEN_FAIL_ON_WARNINGS=ON \
            -DGDAL_BUILD_OPTIONAL_DRIVERS=OFF \
            -DOGR_BUILD_OPTIONAL_DRIVERS=OFF \
            -DGDAL_ENABLE_DRIVER_GTI=ON
          cmake --build . -j$(nproc)

    - name: Print versions
      shell: bash -l {0}
      run: |
          which python3
          python3 --version
          sphinx-build --version
          python3 -m pip list --not-required --format=columns

    - name: Lint .rst files
      shell: bash -l {0}
      run: |
        if find . -name '*.rst' | xargs grep -P '\t'; then echo 'Tabs are bad, please use four spaces in .rst files.'; false; fi
        if find . -name '*.rst' | xargs grep "\.\.versionadded"; then echo 'Wrong annotation. Should be .. versionadded'; false; fi
        if find . -name '*.rst' | xargs grep "\.\.note"; then echo 'Wrong annotation. Should be .. note'; false; fi
        if find . -name '*.rst' | xargs grep "\.\.warning"; then echo 'Wrong annotation. Should be .. warning'; false; fi
        if find . -name '*.rst' | xargs grep "\.\.codeblock"; then echo 'Wrong annotation. Should be .. codeblock'; false; fi
      working-directory: ./doc
    - name: Doxygen
      shell: bash -l {0}
      run: |
        cmake --build . --target doxygen_xml
      working-directory: build
    - name: Spelling
      shell: bash -l {0}
      run: |
        python3 -c 'from osgeo import gdal'
        ctest -V -R spelling --output-on-failure
      working-directory: build