curl/.github/workflows/checkdocs.yml

# 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/**'
      - '**.md'
      - 'docs/*'
  pull_request:
    branches:
      - master
    paths:
      - '.github/workflows/checkdocs.yml'
      - '.github/scripts/**'
      - '**.md'
      - 'docs/*'

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

permissions: {}

jobs:
  proselint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4
        name: checkout

      - name: install prereqs
        run: |
          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list
          sudo apt-get install python3-proselint

      # config file help: https://github.com/amperser/proselint/
      - name: create proselint config
        run: |
          cat <<JSON > $HOME/.proselintrc
          {
            "checks": {
              "typography.diacritical_marks": false,
              "typography.symbols": false,
              "annotations.misc": false,
              "security.password": false
            }
          }
          JSON

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

      - name: check prose
        run: git ls-files -z '*.md' | grep -Evz 'CHECKSRC.md|DISTROS.md|CURLOPT_INTERFACE.md|interface.md' | xargs -0 proselint README

      # This is for CHECKSRC and files with aggressive exclamation mark needs
      - name: create second proselint config
        run: |
          cat <<JSON > $HOME/.proselintrc
          {
            "checks": {
              "typography.diacritical_marks": false,
              "typography.symbols": false,
              "typography.exclamation": false,
              "annotations.misc": false
            }
          }
          JSON

      - name: check special prose
        run: proselint docs/CHECKSRC.md docs/libcurl/opts/CURLOPT_INTERFACE.md docs/cmdline-opts/interface.md

  # Docs: https://github.com/marketplace/actions/markdown-link-check
  linkcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4
        name: checkout

      - name: trim the cmdline docs markdown files
        run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl

      - uses: gaurav-nelson/github-action-markdown-link-check@5c5dfc0ac2e225883c0e5f03a85311ec2830d368 # v1
        with:
          use-quiet-mode: 'yes'

  spellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4
        name: checkout

      - name: trim all man page *.md files
        run: find docs -name "*.md" ! -name "_*" -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl

      - name: trim libcurl man page *.md files
        run: find docs/libcurl \( -name "curl_*.md" -o -name "libcurl*.md" \) -print0 | xargs -0 -n1 .github/scripts/cleanspell.pl

      - name: trim libcurl option man page *.md files
        run: find docs/libcurl/opts -name "CURL*.md" -print0 | xargs -0 -n1 .github/scripts/cleanspell.pl

      - name: trim cmdline docs markdown _*.md files
        run: find docs/cmdline-opts -name "_*.md" -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl --no-header

      - name: setup the custom wordlist
        run: grep -v '^#' .github/scripts/spellcheck.words >  wordlist.txt

      - name: Check Spelling
        uses: rojopolis/spellcheck-github-actions@b83ca7c1b5c285e4f2b43e209a455c74872ec341 # v0
        with:
          config_path: .github/scripts/spellcheck.yaml

  badwords-synopsis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4
        name: checkout

      - name: badwords
        run: .github/scripts/badwords.pl < .github/scripts/badwords.txt docs/*.md docs/libcurl/*.md docs/libcurl/opts/*.md docs/cmdline-opts/*.md docs/TODO docs/KNOWN_BUGS tests/*.md

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

  man-examples:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4
        name: checkout

      - name: render nroff versions
        run: autoreconf -fi && ./configure --without-ssl --without-libpsl && make -C docs

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