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