Skip to content

Commit 9fefd71

Browse files
MatteoPologrutoMatteoPologruto
authored
Merge pull request #28 from arduino/add-check-markdown
Add CI workflow to check Markdown files for problems
2 parents 1600801 + 49e6f3e commit 9fefd71

8 files changed

+1396
-28
lines changed

‎.github/workflows/check-markdown-task.yml

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md
2+
name: Check Markdown
3+
4+
env:
5+
# See: https://github.com/actions/setup-node/#readme
6+
NODE_VERSION: 16.x
7+
8+
# See: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
9+
on:
10+
create:
11+
push:
12+
paths:
13+
- ".github/workflows/check-markdown-task.ya?ml"
14+
- ".markdown-link-check.json"
15+
- "package.json"
16+
- "package-lock.json"
17+
- "Taskfile.ya?ml"
18+
- "**/.markdownlint*"
19+
- "**.mdx?"
20+
- "**.mkdn"
21+
- "**.mdown"
22+
- "**.markdown"
23+
pull_request:
24+
paths:
25+
- ".github/workflows/check-markdown-task.ya?ml"
26+
- ".markdown-link-check.json"
27+
- "package.json"
28+
- "package-lock.json"
29+
- "Taskfile.ya?ml"
30+
- "**/.markdownlint*"
31+
- "**.mdx?"
32+
- "**.mkdn"
33+
- "**.mdown"
34+
- "**.markdown"
35+
schedule:
36+
# Run every Tuesday at 8 AM UTC to catch breakage caused by external changes.
37+
- cron: "0 8 * * TUE"
38+
workflow_dispatch:
39+
repository_dispatch:
40+
41+
jobs:
42+
run-determination:
43+
runs-on: ubuntu-latest
44+
outputs:
45+
result: ${{ steps.determination.outputs.result }}
46+
steps:
47+
- name: Determine if the rest of the workflow should run
48+
id: determination
49+
run: |
50+
RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
51+
# The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
52+
if [[
53+
"${{ github.event_name }}" != "create" ||
54+
"${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
55+
]]; then
56+
# Run the other jobs.
57+
RESULT="true"
58+
else
59+
# There is no need to run the other jobs.
60+
RESULT="false"
61+
fi
62+
63+
echo "result=$RESULT" >> $GITHUB_OUTPUT
64+
65+
lint:
66+
needs: run-determination
67+
if: needs.run-determination.outputs.result == 'true'
68+
runs-on: ubuntu-latest
69+
70+
steps:
71+
- name: Checkout repository
72+
uses: actions/checkout@v3
73+
74+
- name: Setup Node.js
75+
uses: actions/setup-node@v3
76+
with:
77+
node-version: ${{ env.NODE_VERSION }}
78+
79+
- name: Initialize markdownlint-cli problem matcher
80+
uses: xt0rted/markdownlint-problem-matcher@v2
81+
82+
- name: Install Task
83+
uses: arduino/setup-task@v1
84+
with:
85+
repo-token: ${{ secrets.GITHUB_TOKEN }}
86+
version: 3.x
87+
88+
- name: Lint
89+
run: task markdown:lint
90+
91+
links:
92+
needs: run-determination
93+
if: needs.run-determination.outputs.result == 'true'
94+
runs-on: ubuntu-latest
95+
96+
steps:
97+
- name: Checkout repository
98+
uses: actions/checkout@v3
99+
100+
- name: Setup Node.js
101+
uses: actions/setup-node@v3
102+
with:
103+
node-version: ${{ env.NODE_VERSION }}
104+
105+
- name: Install Task
106+
uses: arduino/setup-task@v1
107+
with:
108+
repo-token: ${{ secrets.GITHUB_TOKEN }}
109+
version: 3.x
110+
111+
- name: Check links
112+
run: task --silent markdown:check-links

‎.markdown-link-check.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"httpHeaders": [
3+
{
4+
"urls": ["https://docs.github.com/"],
5+
"headers": {
6+
"Accept-Encoding": "gzip, deflate, br"
7+
}
8+
}
9+
],
10+
"retryOn429": true,
11+
"retryCount": 3,
12+
"aliveStatusCodes": [200, 206]
13+
}

‎.markdownlint.yml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlint.yml
2+
# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
3+
# The code style defined in this file is the official standardized style to be used in all Arduino projects and should
4+
# not be modified.
5+
# Note: Rules disabled solely because they are redundant to Prettier are marked with a "Prettier" comment.
6+
7+
default: false
8+
MD001: false
9+
MD002: false
10+
MD003: false # Prettier
11+
MD004: false # Prettier
12+
MD005: false # Prettier
13+
MD006: false # Prettier
14+
MD007: false # Prettier
15+
MD008: false # Prettier
16+
MD009:
17+
br_spaces: 0
18+
strict: true
19+
list_item_empty_lines: false # Prettier
20+
MD010: false # Prettier
21+
MD011: true
22+
MD012: false # Prettier
23+
MD013: false
24+
MD014: false
25+
MD018: true
26+
MD019: false # Prettier
27+
MD020: true
28+
MD021: false # Prettier
29+
MD022: false # Prettier
30+
MD023: false # Prettier
31+
MD024: false
32+
MD025:
33+
level: 1
34+
front_matter_title: '^\s*"?title"?\s*[:=]'
35+
MD026: false
36+
MD027: false # Prettier
37+
MD028: false
38+
MD029:
39+
style: one
40+
MD030:
41+
ul_single: 1
42+
ol_single: 1
43+
ul_multi: 1
44+
ol_multi: 1
45+
MD031: false # Prettier
46+
MD032: false # Prettier
47+
MD033: false
48+
MD034: false
49+
MD035: false # Prettier
50+
MD036: false
51+
MD037: true
52+
MD038: true
53+
MD039: true
54+
MD040: false
55+
MD041: false
56+
MD042: true
57+
MD043: false
58+
MD044: false
59+
MD045: true
60+
MD046:
61+
style: fenced
62+
MD047: false # Prettier

‎.markdownlintignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlintignore
2+
.licenses/
3+
__pycache__/
4+
node_modules/

‎README.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
# Arduino pluggable discovery for dfu devices
2+
23
[![Sync Labels status](https://github.com/arduino/dfu-discovery/actions/workflows/sync-labels.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/sync-labels.yml)
34
[![Check Go Dependencies status](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-dependencies-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-dependencies-task.yml)
45
[![Check License status](https://github.com/arduino/dfu-discovery/actions/workflows/check-license.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-license.yml)
56
[![Check Go status](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-task.yml)
6-
[![Publish Tester Build status](https://github.com/arduino/dfu-discover/actions/workflows/publish-go-tester-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/publish-go-tester-task.yml)
7+
[![Publish Tester Build status](https://github.com/arduino/dfu-discovery/actions/workflows/publish-go-tester-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/publish-go-tester-task.yml)
78
[![Check Taskfiles status](https://github.com/arduino/dfu-discovery/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-taskfiles.yml)
89
[![Check Workflows status](https://github.com/arduino/dfu-discovery/actions/workflows/check-workflows-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-workflows-task.yml)
10+
[![Check Markdown status](https://github.com/arduino/dfu-discovery/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-markdown-task.yml)
911

1012
The `dfu-discovery` tool is a command line program that interacts via stdio. It accepts commands as plain ASCII strings terminated with LF `\n` and sends response as JSON.
1113

@@ -15,6 +17,7 @@ The `dfu-discovery` tool is a command line program that interacts via stdio. It
1517

1618
Just run `task download-dfu-util` to download dfu-util source code and then `task dist:<platform-to-build>`
1719
The platform to build can be one of:
20+
1821
- Windows_32bit
1922
- Windows_64bit
2023
- Linux_32bit
@@ -286,7 +289,7 @@ e-mail contact: [email protected]
286289

287290
## License
288291

289-
Copyright (c) 2018 ARDUINO SA (www.arduino.cc)
292+
Copyright (c) 2018 ARDUINO SA (https://www.arduino.cc)
290293

291294
The software is released under the GNU General Public License, which covers the main body
292295
of the dfu-discovery code. The terms of this license can be found at:

‎Taskfile.yml

Lines changed: 104 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,39 @@ vars:
3939
)
4040
4141
tasks:
42+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-workflows-task/Taskfile.yml
43+
ci:validate:
44+
desc: Validate GitHub Actions workflows against their JSON schema
45+
vars:
46+
# Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/github-workflow.json
47+
WORKFLOW_SCHEMA_URL: https://json.schemastore.org/github-workflow
48+
WORKFLOW_SCHEMA_PATH:
49+
sh: task utility:mktemp-file TEMPLATE="workflow-schema-XXXXXXXXXX.json"
50+
WORKFLOWS_DATA_PATH: "./.github/workflows/*.{yml,yaml}"
51+
deps:
52+
- task: npm:install-deps
53+
cmds:
54+
- |
55+
wget \
56+
--quiet \
57+
--output-document="{{.WORKFLOW_SCHEMA_PATH}}" \
58+
{{.WORKFLOW_SCHEMA_URL}}
59+
- |
60+
npx \
61+
--package=ajv-cli \
62+
--package=ajv-formats \
63+
ajv validate \
64+
--all-errors \
65+
--strict=false \
66+
-c ajv-formats \
67+
-s "{{.WORKFLOW_SCHEMA_PATH}}" \
68+
-d "{{.WORKFLOWS_DATA_PATH}}"
69+
70+
docs:generate:
71+
desc: Create all generated documentation content
72+
# This is an "umbrella" task used to call any documentation generation processes the project has.
73+
# It can be left empty if there are none.
74+
4275
download-dfu-util:
4376
desc: download dfu-util and copy the files in the correct dir
4477
cmds:
@@ -56,7 +89,7 @@ tasks:
5689
# for some reason quirks.c has the exec flag set
5790
chmod -x dfu-util_quirks.c
5891
fi
59-
92+
6093
download-libusb:
6194
desc: download libusb and copy the files in the correct dir
6295
cmds:
@@ -138,33 +171,80 @@ tasks:
138171
cmds:
139172
- go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
140173

141-
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-workflows-task/Taskfile.yml
142-
ci:validate:
143-
desc: Validate GitHub Actions workflows against their JSON schema
144-
vars:
145-
# Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/github-workflow.json
146-
WORKFLOW_SCHEMA_URL: https://json.schemastore.org/github-workflow
147-
WORKFLOW_SCHEMA_PATH:
148-
sh: task utility:mktemp-file TEMPLATE="workflow-schema-XXXXXXXXXX.json"
149-
WORKFLOWS_DATA_PATH: "./.github/workflows/*.{yml,yaml}"
174+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
175+
markdown:check-links:
176+
desc: Check for broken links
150177
deps:
178+
- task: docs:generate
151179
- task: npm:install-deps
152180
cmds:
153181
- |
154-
wget \
155-
--quiet \
156-
--output-document="{{.WORKFLOW_SCHEMA_PATH}}" \
157-
{{.WORKFLOW_SCHEMA_URL}}
158-
- |
159-
npx \
160-
--package=ajv-cli \
161-
--package=ajv-formats \
162-
ajv validate \
163-
--all-errors \
164-
--strict=false \
165-
-c ajv-formats \
166-
-s "{{.WORKFLOW_SCHEMA_PATH}}" \
167-
-d "{{.WORKFLOWS_DATA_PATH}}"
182+
if [[ "{{.OS}}" == "Windows_NT" ]]; then
183+
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
184+
# so the Windows user is required to have markdown-link-check installed and in PATH.
185+
if ! which markdown-link-check &>/dev/null; then
186+
echo "markdown-link-check not found or not in PATH."
187+
echo "Please install: https://github.com/tcort/markdown-link-check#readme"
188+
exit 1
189+
fi
190+
# Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero
191+
# exit status, but it's better to check all links before exiting.
192+
set +o errexit
193+
STATUS=0
194+
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
195+
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
196+
# \ characters special treatment on Windows in an attempt to support them as path separators.
197+
for file in $(
198+
find . \
199+
-type d -name '.git' -prune -o \
200+
-type d -name '.licenses' -prune -o \
201+
-type d -name '__pycache__' -prune -o \
202+
-type d -name 'node_modules' -prune -o \
203+
-regex ".*[.]md" -print
204+
); do
205+
markdown-link-check \
206+
--quiet \
207+
--config "./.markdown-link-check.json" \
208+
"$file"
209+
STATUS=$(( $STATUS + $? ))
210+
done
211+
exit $STATUS
212+
else
213+
npx --package=markdown-link-check --call='
214+
STATUS=0
215+
for file in $(
216+
find . \
217+
-type d -name '.git' -prune -o \
218+
-type d -name '.licenses' -prune -o \
219+
-type d -name '__pycache__' -prune -o \
220+
-type d -name 'node_modules' -prune -o \
221+
-regex ".*[.]md" -print
222+
); do
223+
markdown-link-check \
224+
--quiet \
225+
--config "./.markdown-link-check.json" \
226+
"$file"
227+
STATUS=$(( $STATUS + $? ))
228+
done
229+
exit $STATUS
230+
'
231+
fi
232+
233+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
234+
markdown:fix:
235+
desc: Automatically correct linting violations in Markdown files where possible
236+
deps:
237+
- task: npm:install-deps
238+
cmds:
239+
- npx markdownlint-cli --fix "**/*.md"
240+
241+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
242+
markdown:lint:
243+
desc: Check for problems in Markdown files
244+
deps:
245+
- task: npm:install-deps
246+
cmds:
247+
- npx markdownlint-cli "**/*.md"
168248

169249
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
170250
npm:install-deps:

0 commit comments

Comments
 (0)