# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
#
# SPDX-License-Identifier: curl

# This workflow contains tests that operate on documentation files only. Some
# checks modify the source so they cannot be combined into a single job.

name: 'Docs'

'on':
  push:
    branches:
      - master
      - '*/ci'
    paths:
      - '.github/workflows/checkdocs.yml'
      - '.github/scripts/**'
      - 'scripts/**'
      - '**.md'
      - 'docs/*'
  pull_request:
    branches:
      - master
    paths:
      - '.github/workflows/checkdocs.yml'
      - '.github/scripts/**'
      - 'scripts/**'
      - '**.md'
      - 'docs/*'

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

permissions: {}

jobs:
  # config file help: https://github.com/amperser/proselint/
  proselint:
    name: 'proselint'
    runs-on: ubuntu-24.04-arm
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: 'install prereqs'
        run: |
          python3 -m venv ~/venv
          ~/venv/bin/pip --disable-pip-version-check --no-input --no-cache-dir install --progress-bar off --prefer-binary -r .github/scripts/requirements-proselint.txt

      - name: 'trim headers off all *.md files'
        run: git ls-files '*.md' -z | xargs -0 -n1 .github/scripts/trimmarkdownheader.pl

      - name: 'check prose'
        run: |
          cat <<JSON > ~/.proselintrc.json
          {
            "checks": {
              "annotations.misc": false,
              "lexical_illusions": false,
              "misc.annotations": false,
              "redundancy.misc.garner": false,
              "security.password": false,
              "spelling.ve_of": false,
              "typography.diacritical_marks": false,
              "typography.symbols": false
            }
          }
          JSON
          source ~/venv/bin/activate
          git ls-files README '*.md' -z | grep -Evz '(CHECKSRC|DISTROS|CURLOPT_INTERFACE|interface)\.md' | xargs -0 proselint check --

      - name: 'check special prose'  # For CHECKSRC and files with aggressive exclamation mark needs
        run: |
          cat <<JSON > ~/.proselintrc.json
          {
            "checks": {
              "annotations.misc": false,
              "lexical_illusions": false,
              "typography.diacritical_marks": false,
              "typography.punctuation.exclamation": false,
              "typography.symbols": false
            }
          }
          JSON
          source ~/venv/bin/activate
          proselint check docs/internals/CHECKSRC.md docs/libcurl/opts/CURLOPT_INTERFACE.md docs/cmdline-opts/interface.md

  pyspelling:
    name: 'pyspelling'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: 'trim all *.md files in docs/'
        run: .github/scripts/cleancmd.pl 'docs/*.md'

      - name: 'install'
        run: |
          sudo rm -f /etc/apt/sources.list.d/{azure-cli.sources,microsoft-prod.list,ondrej-ubuntu-php-noble.sources}
          sudo apt-get -o Dpkg::Use-Pty=0 update
          sudo apt-get -o Dpkg::Use-Pty=0 install aspell aspell-en
          python3 -m venv ~/venv
          ~/venv/bin/pip --disable-pip-version-check --no-input --no-cache-dir install --progress-bar off --prefer-binary -r .github/scripts/requirements-docs.txt

      - name: 'check spelling'
        run: |
          source ~/venv/bin/activate
          # setup the custom wordlist
          grep -v '^#' .github/scripts/pyspelling.words > wordlist.txt
          aspell --version
          pyspelling --version
          pyspelling --verbose --jobs 5 --config .github/scripts/pyspelling.yaml

  synopsis-man-examples:
    name: 'synopsis, man-examples'
    runs-on: ubuntu-24.04-arm
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: 'verify synopsis'
        run: .github/scripts/verify-synopsis.pl docs/libcurl/curl*.md

      - name: 'verify examples'
        run: .github/scripts/verify-examples.pl docs/libcurl/curl*.md docs/libcurl/opts/*.md