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