name: Check Documentation

on:
  pull_request:
    branches:
      - '*'
    paths:
      - '.github/workflows/check_doc.yaml'
      - 'docs/**'

jobs:

  docs:
    name: lint, build and verify
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
        with:
          fetch-depth: 0

      - name: Install markdownlint
        run: |
          npm install --global markdownlint@0.29.0 markdownlint-cli@0.35.0

      - name: Lint
        run: ./docs/scripts/lint.sh docs

      - name: Setup python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: '3.12'
          cache: 'pip'
          cache-dependency-path: "./docs/requirements.txt"

      - name: Build documentation
        working-directory: ./docs
        run: |
          pip install -r requirements.txt
          mkdocs build --strict

      - name: Setup ruby
        uses: ruby/setup-ruby@e69dcf3ded5967f30d7ef595704928d91cdae930 # v1.285.0
        with:
          ruby-version: '3.4'

      - name: Install html-proofer
        run: |
          gem install nokogiri --version 1.18.6 --no-document -- --use-system-libraries
          gem install html-proofer --version 5.0.10 --no-document -- --use-system-libraries
        env:
          NOKOGIRI_USE_SYSTEM_LIBRARIES: "true"

      # Comes from https://github.com/gjtorikian/html-proofer?tab=readme-ov-file#caching-with-continuous-integration
      - name: Cache HTMLProofer
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          path: tmp/.htmlproofer
          key: ${{ runner.os }}-htmlproofer

      - name: Verify
        run: ./docs/scripts/verify.sh docs/site