Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit f2a37a7

Browse files
authored
Merge pull request #261 from per1234/rule-docs
Publish generated list of rules on documentation website
2 parents 1af853e + ff3b56a commit f2a37a7

File tree

26 files changed

+3629
-673
lines changed

26 files changed

+3629
-673
lines changed

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,10 +50,20 @@ jobs:
5050
echo "::set-output name=result::$RESULT"
5151
5252
check-errors:
53+
name: check-errors (${{ matrix.module.path }})
5354
needs: run-determination
5455
if: needs.run-determination.outputs.result == 'true'
5556
runs-on: ubuntu-latest
5657

58+
strategy:
59+
fail-fast: false
60+
61+
matrix:
62+
module:
63+
- path: ./
64+
- path: docsgen
65+
- path: ruledocsgen
66+
5767
steps:
5868
- name: Checkout repository
5969
uses: actions/checkout@v2
@@ -70,13 +80,25 @@ jobs:
7080
version: 3.x
7181

7282
- name: Check for errors
83+
env:
84+
GO_MODULE_PATH: ${{ matrix.module.path }}
7385
run: task go:vet
7486

7587
check-outdated:
88+
name: check-outdated (${{ matrix.module.path }})
7689
needs: run-determination
7790
if: needs.run-determination.outputs.result == 'true'
7891
runs-on: ubuntu-latest
7992

93+
strategy:
94+
fail-fast: false
95+
96+
matrix:
97+
module:
98+
- path: ./
99+
- path: docsgen
100+
- path: ruledocsgen
101+
80102
steps:
81103
- name: Checkout repository
82104
uses: actions/checkout@v2
@@ -93,16 +115,28 @@ jobs:
93115
version: 3.x
94116

95117
- name: Modernize usages of outdated APIs
118+
env:
119+
GO_MODULE_PATH: ${{ matrix.module.path }}
96120
run: task go:fix
97121

98122
- name: Check if any fixes were needed
99123
run: git diff --color --exit-code
100124

101125
check-style:
126+
name: check-style (${{ matrix.module.path }})
102127
needs: run-determination
103128
if: needs.run-determination.outputs.result == 'true'
104129
runs-on: ubuntu-latest
105130

131+
strategy:
132+
fail-fast: false
133+
134+
matrix:
135+
module:
136+
- path: ./
137+
- path: docsgen
138+
- path: ruledocsgen
139+
106140
steps:
107141
- name: Checkout repository
108142
uses: actions/checkout@v2
@@ -122,13 +156,25 @@ jobs:
122156
run: go install golang.org/x/lint/golint@latest
123157

124158
- name: Check style
159+
env:
160+
GO_MODULE_PATH: ${{ matrix.module.path }}
125161
run: task --silent go:lint
126162

127163
check-formatting:
164+
name: check-formatting (${{ matrix.module.path }})
128165
needs: run-determination
129166
if: needs.run-determination.outputs.result == 'true'
130167
runs-on: ubuntu-latest
131168

169+
strategy:
170+
fail-fast: false
171+
172+
matrix:
173+
module:
174+
- path: ./
175+
- path: docsgen
176+
- path: ruledocsgen
177+
132178
steps:
133179
- name: Checkout repository
134180
uses: actions/checkout@v2
@@ -145,6 +191,8 @@ jobs:
145191
version: 3.x
146192

147193
- name: Format code
194+
env:
195+
GO_MODULE_PATH: ${{ matrix.module.path }}
148196
run: task go:format
149197

150198
- name: Check formatting
@@ -163,6 +211,7 @@ jobs:
163211
module:
164212
- path: ./
165213
- path: docsgen
214+
- path: ruledocsgen
166215

167216
steps:
168217
- name: Checkout repository

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ on:
1818
- "pyproject.toml"
1919
- "docs/**"
2020
- "docsgen/**"
21+
- "ruledocsgen/**"
2122
- "**.go"
2223
pull_request:
2324
paths:
@@ -28,6 +29,7 @@ on:
2829
- "pyproject.toml"
2930
- "docs/**"
3031
- "docsgen/**"
32+
- "ruledocsgen/**"
3133
- "**.go"
3234
workflow_dispatch:
3335
repository_dispatch:

‎.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ on:
2020
- "Taskfile.ya?ml"
2121
- "**.go"
2222
- "docsgen/**"
23+
- "ruledocsgen/**"
2324
- "mkdocs.ya?ml"
2425
- "poetry.lock"
2526
- "pyproject.toml"

‎.github/workflows/test-go-task.yml‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,17 @@ on:
1212
paths:
1313
- ".github/workflows/test-go-task.ya?ml"
1414
- "codecov.ya?ml"
15-
- "go.mod"
16-
- "go.sum"
15+
- "**/go.mod"
16+
- "**/go.sum"
1717
- "Taskfile.ya?ml"
1818
- "**.go"
1919
- "**/testdata/**"
2020
pull_request:
2121
paths:
2222
- ".github/workflows/test-go-task.ya?ml"
2323
- "codecov.ya?ml"
24-
- "go.mod"
25-
- "go.sum"
24+
- "**/go.mod"
25+
- "**/go.sum"
2626
- "Taskfile.ya?ml"
2727
- "**.go"
2828
- "**/testdata/**"
@@ -54,15 +54,23 @@ jobs:
5454
echo "::set-output name=result::$RESULT"
5555
5656
test:
57+
name: test (${{ matrix.module.path }} - ${{ matrix.operating-system }})
5758
needs: run-determination
5859
if: needs.run-determination.outputs.result == 'true'
5960

6061
strategy:
62+
fail-fast: false
63+
6164
matrix:
6265
operating-system:
6366
- ubuntu-latest
6467
- windows-latest
6568
- macos-latest
69+
module:
70+
- path: ./
71+
codecov-flags: unit
72+
- path: ruledocsgen/
73+
codecov-flags: unit
6674

6775
runs-on: ${{ matrix.operating-system }}
6876

@@ -82,12 +90,14 @@ jobs:
8290
version: 3.x
8391

8492
- name: Run tests
93+
env:
94+
GO_MODULE_PATH: ${{ matrix.module.path }}
8595
run: task go:test
8696

8797
- name: Send unit tests coverage to Codecov
88-
if: matrix.operating-system == 'ubuntu-latest'
98+
if: runner.os == 'Linux'
8999
uses: codecov/codecov-action@v2
90100
with:
91-
file: ./coverage_unit.txt
92-
flags: unit
101+
file: ${{ matrix.module.path }}coverage_unit.txt
102+
flags: ${{ matrix.module.codecov-flags }}
93103
fail_ci_if_error: ${{ github.repository == 'arduino/arduino-lint' }}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,5 +18,8 @@ coverage_unit.txt
1818
/docsgen/arduino-cli
1919
/docsgen/arduino-cli.exe
2020
/docs/commands/*.md
21+
/ruledocsgen/ruledocsgen
22+
/ruledocsgen/ruledocsgen.exe
23+
/docs/rules/
2124

2225
/dist

‎.prettierignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@
99
/internal/project/projectdata/testdata/packageindexes/invalid-JSON/package_foo_index.json
1010
/internal/rule/rulefunction/testdata/packageindexes/invalid-JSON/package_foo_index.json
1111
/internal/rule/rulefunction/testdata/sketches/InvalidJSONMetadataFile/sketch.json
12+
/ruledocsgen/testdata/golden

‎Taskfile.yml‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,19 @@ vars:
88
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/release-go-task/Taskfile.yml
99
PROJECT_NAME: "arduino-lint"
1010
DIST_DIR: "dist"
11+
# Path of the project's primary Go module:
12+
DEFAULT_GO_MODULE_PATH: ./
1113
DEFAULT_GO_PACKAGES:
12-
sh: echo $(go list ./... | grep --invert-match 'github.com/arduino/arduino-lint/internal/rule/schema/schemadata' | tr '\n' ' ')
14+
sh: |
15+
echo $( \
16+
cd {{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}} \
17+
&& \
18+
go list ./... | \
19+
grep --invert-match 'github.com/arduino/arduino-lint/internal/rule/schema/schemadata' | \
20+
tr '\n' ' ' \
21+
|| \
22+
echo '"ERROR: Unable to discover Go packages"' \
23+
)
1324
# build vars
1425
COMMIT:
1526
sh: echo "$(git log --no-show-signature -n 1 --format=%h)"
@@ -95,6 +106,7 @@ tasks:
95106
desc: Create all generated documentation content
96107
deps:
97108
- task: go:cli-docs
109+
- task: go:rule-docs
98110
# Make the formatting consistent with the non-generated Markdown
99111
- task: general:format-prettier
100112

@@ -134,6 +146,7 @@ tasks:
134146
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/go-task/Taskfile.yml
135147
go:build:
136148
desc: Build the Go code
149+
dir: "{{.DEFAULT_GO_MODULE_PATH}}"
137150
cmds:
138151
- go build -v {{.LDFLAGS}}
139152

@@ -150,12 +163,14 @@ tasks:
150163
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
151164
go:fix:
152165
desc: Modernize usages of outdated APIs
166+
dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
153167
cmds:
154168
- go fix {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
155169

156170
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
157171
go:format:
158172
desc: Format Go code
173+
dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
159174
cmds:
160175
- go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
161176

@@ -172,6 +187,7 @@ tasks:
172187
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
173188
go:lint:
174189
desc: Lint Go code
190+
dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
175191
cmds:
176192
- |
177193
if ! which golint &>/dev/null; then
@@ -183,9 +199,24 @@ tasks:
183199
{{default "-min_confidence 0.8 -set_exit_status" .GO_LINT_FLAGS}} \
184200
{{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
185201
202+
go:rule-docs:
203+
desc: Generate rules documentation
204+
dir: ./ruledocsgen
205+
deps:
206+
- task: go:rule-docs:build
207+
cmds:
208+
- ./ruledocsgen ../docs/rules
209+
210+
go:rule-docs:build:
211+
desc: Generate rules documentation
212+
dir: ./ruledocsgen
213+
cmds:
214+
- go build
215+
186216
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-task/Taskfile.yml
187217
go:test:
188218
desc: Run unit tests
219+
dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
189220
cmds:
190221
- |
191222
go test \
@@ -201,13 +232,16 @@ tasks:
201232
desc: Run integration tests
202233
deps:
203234
- task: go:build
235+
- task: go:rule-docs:build
204236
- task: poetry:install-deps
205237
cmds:
206238
- poetry run pytest tests
239+
- poetry run pytest ruledocsgen/tests
207240

208241
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
209242
go:vet:
210243
desc: Check for errors in Go code
244+
dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}"
211245
cmds:
212246
- go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
213247

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
**Arduino Lint** is a command line tool that checks for common problems with [Arduino](https://www.arduino.cc/)
22
projects.
33

4-
Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. Rules cover
5-
specification compliance, Library Manager submission requirements, and best practices.
4+
Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. [Rules](rules.md)
5+
cover specification compliance, Library Manager submission requirements, and best practices.
66

77
## Installation
88

‎docs/rules.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
**Arduino Lint** inspects Arduino projects for common problems. This is done by checking the project against a series of
2+
"rules", each of which is targeted to detecting a specific potential issue. Only the rules of relevance to the project
3+
being linted are applied.
4+
5+
## Rule documentation
6+
7+
Additional information is available for each of the **Arduino Lint** rules, organized by project type:
8+
9+
- [Sketch](rules/sketch.md)
10+
- [Library](rules/library.md)
11+
- [Boards platform](rules/platform.md)
12+
- [Package index](rules/package-index.md)
13+
14+
## Rule ID
15+
16+
In order to allow particular rules to be referenced unequivocally, each has been assigned a permanent unique
17+
identification code (e.g., `SS001`).
18+
19+
## Rule level
20+
21+
In addition to checking for critical flaws, **Arduino Lint** also advocates for best practices in Arduino projects. For
22+
this reason, not all rule violations are treated as fatal linting errors.
23+
24+
A violation of a rule is assigned a level according to its severity. In cases where a rule violation indicates a serious
25+
problem with the project, the violation is treated as an error, and will result in a non-zero exit status from the
26+
`arduino-lint` command. In cases where the violation indicates a possible problem, or where the rule is a recommendation
27+
for an optional improvement to enhance the project user's experience, the violation is treated as a warning. It is hoped
28+
that these warning-level violations will be given consideration by the user, but they do not affect the `arduino-lint`
29+
exit status.
30+
31+
Of the hundreds of rules provided by **Arduino Lint**, only the ones relevant to the current target project are applied,
32+
with the rest disabled.
33+
34+
The rule levels and enabled subset of rules is dependent on the target project type and how the user has configured
35+
Arduino Lint via the [command line flags](commands/arduino-lint.md) and
36+
[environment variables](index.md#environment-variables).
37+
38+
## Projects and "superprojects"
39+
40+
Arduino projects may contain other Arduino projects as subprojects. For example, the libraries
41+
[bundled](https://arduino.github.io/arduino-cli/latest/platform-specification/#platform-bundled-libraries) with an
42+
Arduino boards platform. These subprojects may, in turn, contain their own subprojects, such as the example sketches
43+
included with a platform bundled library.
44+
45+
**Arduino Lint** also lints any subprojects the target project might contain. The type of the top level "superproject"
46+
is a factor in the configuration of some rules. For example, there is no need to take Library Manager requirements into
47+
consideration in the case of a platform bundled library, since it will never be distributed via that system.

‎internal/result/result.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,9 @@ func (results *Type) Record(lintedProject project.Type, ruleConfiguration ruleco
109109
ruleMessage := ""
110110
if ruleResult == ruleresult.Fail {
111111
ruleMessage = message(ruleConfiguration.MessageTemplate, ruleOutput)
112+
if ruleConfiguration.Reference != "" {
113+
ruleMessage = fmt.Sprintf("%s\nSee: %s", ruleMessage, ruleConfiguration.Reference)
114+
}
112115
} else {
113116
// Rules may provide an explanation for their non-fail result.
114117
// The message template should not be used in this case, since it is written for a failure result.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /