xref: /curl/.github/workflows/checkdocs.yml (revision f73f6bf9) 
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@692973e3d937129bcbf40652eb9f2f61becf3332 # 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 install python3-proselint
46
47      # config file help: https://github.com/amperser/proselint/
48      - name: create proselint config
49        run: |
50          cat <<JSON > $HOME/.proselintrc
51          {
52            "checks": {
53              "typography.diacritical_marks": false,
54              "typography.symbols": false,
55              "annotations.misc": false,
56              "security.password": false
57            }
58          }
59          JSON
60
61      - name: trim headers off all *.md files
62        run: git ls-files -z '*.md' | xargs -0 -n1 .github/scripts/trimmarkdownheader.pl
63
64      - name: check prose
65        run: git ls-files -z '*.md' | grep -Evz 'CHECKSRC.md|DISTROS.md|CURLOPT_INTERFACE.md|interface.md' | xargs -0 proselint README
66
67      # This is for CHECKSRC and files with aggressive exclamation mark needs
68      - name: create second proselint config
69        run: |
70          cat <<JSON > $HOME/.proselintrc
71          {
72            "checks": {
73              "typography.diacritical_marks": false,
74              "typography.symbols": false,
75              "typography.exclamation": false,
76              "annotations.misc": false
77            }
78          }
79          JSON
80
81      - name: check special prose
82        run: proselint docs/CHECKSRC.md docs/libcurl/opts/CURLOPT_INTERFACE.md docs/cmdline-opts/interface.md
83
84  # Docs: https://github.com/marketplace/actions/markdown-link-check
85  linkcheck:
86    runs-on: ubuntu-latest
87    steps:
88      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
89        name: checkout
90
91      - name: trim the cmdline docs markdown files
92        run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl
93
94      - uses: gaurav-nelson/github-action-markdown-link-check@5c5dfc0ac2e225883c0e5f03a85311ec2830d368 # v1
95        with:
96          use-quiet-mode: 'yes'
97
98  spellcheck:
99    runs-on: ubuntu-latest
100    steps:
101      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
102        name: checkout
103
104      - name: trim all man page *.md files
105        run: find docs -name "*.md" ! -name "_*" -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl
106
107      - name: trim libcurl man page *.md files
108        run: find docs/libcurl \( -name "curl_*.md" -o -name "libcurl*.md" \) -print0 | xargs -0 -n1 .github/scripts/cleanspell.pl
109
110      - name: trim libcurl option man page *.md files
111        run: find docs/libcurl/opts -name "CURL*.md" -print0 | xargs -0 -n1 .github/scripts/cleanspell.pl
112
113      - name: trim cmdline docs markdown _*.md files
114        run: find docs/cmdline-opts -name "_*.md" -print0 | xargs -0 -n1 .github/scripts/cleancmd.pl --no-header
115
116      - name: setup the custom wordlist
117        run: grep -v '^#' .github/scripts/spellcheck.words >  wordlist.txt
118
119      - name: Check Spelling
120        uses: rojopolis/spellcheck-github-actions@a0fba0ca8b9e552d4241ea5ccfaa4ca4162622d0 # v0
121        with:
122          config_path: .github/scripts/spellcheck.yaml
123
124  badwords-synopsis:
125    runs-on: ubuntu-latest
126    steps:
127      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
128        name: checkout
129
130      - name: badwords
131        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
132
133      - name: verify-synopsis
134        run: .github/scripts/verify-synopsis.pl docs/libcurl/curl*.md
135
136  man-examples:
137    runs-on: ubuntu-latest
138    steps:
139      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
140        name: checkout
141
142      - name: render nroff versions
143        run: autoreconf -fi && ./configure --without-ssl --without-libpsl && make -C docs
144
145      - name: verify examples
146        run: .github/scripts/verify-examples.pl docs/libcurl/curl*.3 docs/libcurl/opts/*.3
147