xref: /curl/.github/workflows/checkdocs.yml (revision b723f6a4) 
1# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
2#
3# SPDX-License-Identifier: curl
4
5# This workflow contains tests that operate on documentation files only. Some
6# checks modify the source so they cannot be combined into a single job.
7
8name: Docs
9
10'on':
11  push:
12    branches:
13      - master
14      - '*/ci'
15    paths:
16      - '.github/workflows/checkdocs.yml'
17      - '.github/scripts/**'
18      - '**.md'
19      - 'docs/*'
20  pull_request:
21    branches:
22      - master
23    paths:
24      - '.github/workflows/checkdocs.yml'
25      - '.github/scripts/**'
26      - '**.md'
27      - 'docs/*'
28
29concurrency:
30  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
31  cancel-in-progress: true
32
33permissions: {}
34
35jobs:
36  #  proselint:
37  #    runs-on: ubuntu-latest
38  #    steps:
39  #      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4
40  #        name: checkout
41  #
42  #      - name: install prereqs
43  #        run: |
44  #          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list
45  #          sudo apt-get update -y
46  #          sudo apt-get install -y --no-install-suggests --no-install-recommends \
47  #            python3-proselint
48  #
49  #      # config file help: https://github.com/amperser/proselint/
50  #      - name: create proselint config
51  #        run: |
52  #          cat <<JSON > $HOME/.proselintrc.json
53  #          {
54  #            "checks": {
55  #              "typography.diacritical_marks": false,
56  #              "typography.symbols": false,
57  #              "annotations.misc": false,
58  #              "security.password": false,
59  #              "misc.annotations": false
60  #            }
61  #          }
62  #          JSON
63  #
64  #      - name: trim headers off all *.md files
65  #        run: git ls-files -z '*.md' | xargs -0 -n1 .github/scripts/trimmarkdownheader.pl
66  #
67  #      - name: check prose
68  #        run: git ls-files -z '*.md' | grep -Evz 'CHECKSRC.md|DISTROS.md|curl_mprintf.md|CURLOPT_INTERFACE.md|interface.md' | xargs -0 proselint README
69  #
70  #      # This is for CHECKSRC and files with aggressive exclamation mark needs
71  #      - name: create second proselint config
72  #        run: |
73  #          cat <<JSON > $HOME/.proselintrc.json
74  #          {
75  #            "checks": {
76  #              "typography.diacritical_marks": false,
77  #              "typography.symbols": false,
78  #              "typography.exclamation": false,
79  #              "lexical_illusions.misc": false,
80  #              "annotations.misc": false
81  #            }
82  #          }
83  #          JSON
84  #
85  #      - name: check special prose
86  #        run: proselint docs/internals/CHECKSRC.md docs/libcurl/curl_mprintf.md docs/libcurl/opts/CURLOPT_INTERFACE.md docs/cmdline-opts/interface.md
87
88  # Docs: https://github.com/marketplace/actions/markdown-link-check
89  linkcheck:
90    runs-on: ubuntu-latest
91    steps:
92      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
93        name: checkout
94
95      - name: trim the cmdline docs markdown files
96        run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl
97
98      - uses: gaurav-nelson/github-action-markdown-link-check@5c5dfc0ac2e225883c0e5f03a85311ec2830d368 # v1
99        with:
100          use-quiet-mode: 'yes'
101
102  spellcheck:
103    runs-on: ubuntu-latest
104    steps:
105      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
106        name: checkout
107
108      - name: trim all man page *.md files
109        run: find docs -name "*.md" ! -name "_*" -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl
110
111      - name: trim libcurl man page *.md files
112        run: find docs/libcurl \( -name "curl_*.md" -o -name "libcurl*.md" \) -print0 | xargs -0 -n1 .github/scripts/cleanspell.pl
113
114      - name: trim libcurl option man page *.md files
115        run: find docs/libcurl/opts -name "CURL*.md" -print0 | xargs -0 -n1 .github/scripts/cleanspell.pl
116
117      - name: trim cmdline docs markdown _*.md files
118        run: find docs/cmdline-opts -name "_*.md" -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl --no-header
119
120      - name: setup the custom wordlist
121        run: grep -v '^#' .github/scripts/spellcheck.words >  wordlist.txt
122
123      - name: Check Spelling
124        uses: rojopolis/spellcheck-github-actions@403efe0642148e94ecb3515e89c767b85a32371a # v0
125        with:
126          config_path: .github/scripts/spellcheck.yaml
127
128  badwords-synopsis:
129    runs-on: ubuntu-latest
130    steps:
131      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
132        name: checkout
133
134      - name: badwords
135        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
136
137      - name: verify-synopsis
138        run: .github/scripts/verify-synopsis.pl docs/libcurl/curl*.md
139
140  man-examples:
141    runs-on: ubuntu-latest
142    steps:
143      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
144        name: checkout
145
146      - name: render nroff versions
147        run: autoreconf -fi && ./configure --without-ssl --without-libpsl && make -C docs
148
149      - name: verify examples
150        run: .github/scripts/verify-examples.pl docs/libcurl/curl*.3 docs/libcurl/opts/*.3
151
152  miscchecks:
153    runs-on: ubuntu-24.04
154    timeout-minutes: 5
155    steps:
156      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
157        name: checkout
158
159      - name: spacecheck
160        run: .github/scripts/spacecheck.pl
161