Skip to content

Commit f62a372

Browse files
per1234per1234
committed
Escape Markdown markup in rule reference Brief text
The primary purpose of text of the rule configuration's `Description` field is for display in the rule reference section of the documentation website. For this reason, it is written in Markdown, and thus can be output as is. The situation is different with the rule configuration's `Brief` field, since it is displayed prominently in the tool output. For this reason, the use of Markdown would not be appropriate. This text may contain incidental markup characters that would result in unwanted formatting and thus the `Brief` field text must be escaped for display on the website.
1 parent 5fc2ed4 commit f62a372

File tree

5 files changed

+30
-14
lines changed

5 files changed

+30
-14
lines changed

Diff for: ‎ruledocsgen/go.mod

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ go 1.16
55
replace github.com/arduino/arduino-lint => ../
66

77
require (
8+
github.com/JohannesKaufmann/html-to-markdown v1.3.0
89
github.com/arduino/arduino-lint v0.0.0
910
github.com/arduino/go-paths-helper v1.6.1
1011
github.com/olekukonko/tablewriter v0.0.5

Diff for: ‎ruledocsgen/go.sum

+8
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym
4646
github.com/DATA-DOG/go-sqlmock v1.3.3/go.mod h1:f/Ixk793poVmq4qj/V1dPUg2JEAKC73Q5eFN3EC/SaM=
4747
github.com/DataDog/datadog-go v4.0.0+incompatible/go.mod h1:LButxg5PwREeZtORoXG3tL4fMGNddJ+vMq1mwgfaqoQ=
4848
github.com/GeertJohan/go.incremental v1.0.0/go.mod h1:6fAjUhbVuX1KcMD3c8TEgVUqmo4seqhv0i0kdATSkM0=
49+
github.com/JohannesKaufmann/html-to-markdown v1.3.0 h1:K/p4cq8Ib13hcSVcKQNfKCSWw93CYW5pAjY0fl85has=
50+
github.com/JohannesKaufmann/html-to-markdown v1.3.0/go.mod h1:JNSClIRYICFDiFhw6RBhBeWGnMSSKVZ6sPQA+TK4tyM=
4951
github.com/Masterminds/semver v1.4.2/go.mod h1:MB6lktGJrhw8PrUyiEoblNEGEQ+RzHPF078ddwwvV3Y=
5052
github.com/Masterminds/semver/v3 v3.0.3/go.mod h1:VPu/7SZ7ePZ3QOrcuXROw5FAcLl4a0cBrbBpGY/8hQs=
5153
github.com/Microsoft/go-winio v0.4.11/go.mod h1:VhR8bwka0BXejwEJY73c50VrPtXAaKcyvVC4A4RozmA=
@@ -58,6 +60,7 @@ github.com/OneOfOne/xxhash v1.2.8 h1:31czK/TI9sNkxIKfaUfGlU47BAxQ0ztGgd9vPyqimf8
5860
github.com/OneOfOne/xxhash v1.2.8/go.mod h1:eZbhyaAYD41SGSSsnmcpxVoRiQ/MPUTjUdIIOT9Um7Q=
5961
github.com/ProtonMail/go-crypto v0.0.0-20210428141323-04723f9f07d7 h1:YoJbenK9C67SkzkDfmQuVln04ygHj3vjZfd9FL+GmQQ=
6062
github.com/ProtonMail/go-crypto v0.0.0-20210428141323-04723f9f07d7/go.mod h1:z4/9nQmJSSwwds7ejkxaJwO37dru3geImFUdJlaLzQo=
63+
github.com/PuerkitoBio/goquery v1.5.1/go.mod h1:GsLWisAFVj4WgDibEWF4pvYnkVQBpKBKeU+7zCJoLcc=
6164
github.com/PuerkitoBio/purell v1.1.0/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
6265
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
6366
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
@@ -72,6 +75,7 @@ github.com/alcortesm/tgz v0.0.0-20161220082320-9c5fe88206d7 h1:uSoVVbwJiQipAclBb
7275
github.com/alcortesm/tgz v0.0.0-20161220082320-9c5fe88206d7/go.mod h1:6zEj6s6u/ghQa61ZWa/C2Aw3RkjiTBOix7dkqa1VLIs=
7376
github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
7477
github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0=
78+
github.com/andybalholm/cascadia v1.1.0/go.mod h1:GsXiBklL0woXo1j/WYWtSYYC4ouU9PqHO0sqidkEA4Y=
7579
github.com/anmitsu/go-shlex v0.0.0-20161002113705-648efa622239/go.mod h1:2FmKhYUyUczH0OGQWaF5ceTx0UBShxjsH6f8oGKYe2c=
7680
github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be h1:9AeTilPcZAjCFIImctFaOjnTIavg87rW78vTPkQqLI8=
7781
github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be/go.mod h1:ySMOLuWl6zY27l47sB3qLNK6tF2fkHG55UZxx8oIVo4=
@@ -1079,6 +1083,7 @@ github.com/schollz/closestmatch v2.1.0+incompatible/go.mod h1:RtP1ddjLong6gTkbtm
10791083
github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529/go.mod h1:DxrIzT+xaE7yg65j358z/aeFdxmN0P9QXhEzd20vsDc=
10801084
github.com/seatgeek/logrus-gelf-formatter v0.0.0-20210219220335-367fa274be2c h1:jwWrlqKHQeSRjTskQaHBtCOWbaMsd54NBAnofYbEHGs=
10811085
github.com/seatgeek/logrus-gelf-formatter v0.0.0-20210219220335-367fa274be2c/go.mod h1:/THDZYi7F/BsVEcYzYPqdcWFQ+1C2InkawTKfLOAnzg=
1086+
github.com/sebdah/goldie/v2 v2.5.1/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
10821087
github.com/segmentio/analytics-go v3.0.1+incompatible/go.mod h1:C7CYBtQWk4vRk2RyLu0qOcbHJ18E3F1HV2C/8JvKN48=
10831088
github.com/segmentio/analytics-go v3.1.0+incompatible/go.mod h1:C7CYBtQWk4vRk2RyLu0qOcbHJ18E3F1HV2C/8JvKN48=
10841089
github.com/segmentio/backo-go v0.0.0-20160424052352-204274ad699c/go.mod h1:kJ9mm9YmoWSkk+oQ+5Cj8DEoRCX2JT6As4kEtIIOp1M=
@@ -1221,6 +1226,7 @@ github.com/xtgo/uuid v0.0.0-20140804021211-a0b114877d4c/go.mod h1:UrdRz5enIKZ63M
12211226
github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
12221227
github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
12231228
github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
1229+
github.com/yuin/goldmark v1.2.0/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
12241230
github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
12251231
github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
12261232
github.com/zenazn/goji v0.9.0/go.mod h1:7S9M489iMyHBNxwZnk9/EHS098H4/F6TATF2mIxtB1Q=
@@ -1364,6 +1370,7 @@ golang.org/x/mod v0.4.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
13641370
golang.org/x/mod v0.4.1/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
13651371
golang.org/x/mod v0.4.2 h1:Gz96sIWK3OalVv/I/qNygP42zyoKp3xptRVCWRFEBvo=
13661372
golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
1373+
golang.org/x/net v0.0.0-20180218175443-cbe0f9307d01/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
13671374
golang.org/x/net v0.0.0-20180406214816-61147c48b25b/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
13681375
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
13691376
golang.org/x/net v0.0.0-20180816102801-aaf60122140d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -1405,6 +1412,7 @@ golang.org/x/net v0.0.0-20200219183655-46282727080f/go.mod h1:z5CRVTTTmAJ677TzLL
14051412
golang.org/x/net v0.0.0-20200222125558-5a598a2470a0/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
14061413
golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
14071414
golang.org/x/net v0.0.0-20200301022130-244492dfa37a/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
1415+
golang.org/x/net v0.0.0-20200320220750-118fecf932d8/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
14081416
golang.org/x/net v0.0.0-20200324143707-d3edc9973b7e/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
14091417
golang.org/x/net v0.0.0-20200501053045-e0ff5e5a1de5/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
14101418
golang.org/x/net v0.0.0-20200506145744-7e3656a0809f/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=

Diff for: ‎ruledocsgen/main.go

+9-2
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import (
66
"os"
77
"text/template"
88

9+
"github.com/JohannesKaufmann/html-to-markdown/escape"
910
"github.com/arduino/arduino-lint/internal/cli"
1011
"github.com/arduino/arduino-lint/internal/configuration"
1112
"github.com/arduino/arduino-lint/internal/configuration/rulemode"
@@ -37,15 +38,21 @@ func generateRulesDocumentation(ruleConfigurations []ruleconfiguration.Type, out
3738
projecttype.PackageIndex: "https://arduino.github.io/arduino-cli/latest/package_index_json-specification/",
3839
}
3940

41+
templateFunctions := template.FuncMap{
42+
// Some the rule config text is intended for use in both tool output and in the reference, so can't be formatted at
43+
// the source as Markdown. Incidental markup characters in that text must be escaped.
44+
"escape": escape.MarkdownCharacters,
45+
}
46+
4047
projectRulesIntroTemplate := template.Must(template.New("messageTemplate").Parse(
4148
"Arduino Lint provides {{.RuleCount}} rules for the [`{{.ProjectType}}`]({{.ProjectTypeReference}}) project type:\n",
4249
))
43-
ruleDocumentationTemplate := template.Must(template.New("messageTemplate").Parse(`
50+
ruleDocumentationTemplate := template.Must(template.New("messageTemplate").Funcs(templateFunctions).Parse(`
4451
---
4552
4653
<a id="{{.ID}}"></a>
4754
48-
## {{.Brief}} (` + "`" + `{{.ID}}` + "`" + `)
55+
## {{escape .Brief}} (` + "`" + `{{.ID}}` + "`" + `)
4956
5057
{{.Description}}
5158

Diff for: ‎ruledocsgen/main_test.go

+7-7
Original file line numberDiff line numberDiff line change
@@ -111,18 +111,18 @@ func TestAll(t *testing.T) {
111111
ProjectType: projecttype.PackageIndex,
112112
SuperprojectType: projecttype.All,
113113
Category: "data",
114-
Subcategory: "general",
115-
ID: "IS001",
116-
Brief: "missing",
117-
Description: "No package index file was found in the specified project path.",
118-
MessageTemplate: "No package index was found in specified project path.",
119-
Reference: "https://arduino.github.io/arduino-cli/latest/package_index_json-specification/",
114+
Subcategory: "package",
115+
ID: "IA004",
116+
Brief: "packages[*].name missing",
117+
Description: "The package index has a package without a `name` property.",
118+
MessageTemplate: "Missing packages[*].name property in package(s): {{.}}",
119+
Reference: "https://arduino.github.io/arduino-cli/latest/package_index_json-specification/#json-index-file-contents",
120120
DisableModes: nil,
121121
EnableModes: []rulemode.Type{rulemode.Default},
122122
InfoModes: nil,
123123
WarningModes: nil,
124124
ErrorModes: []rulemode.Type{rulemode.Default},
125-
RuleFunction: rulefunction.PackageIndexMissing,
125+
RuleFunction: rulefunction.PackageIndexPackagesNameMissing,
126126
},
127127
}
128128

Diff for: ‎ruledocsgen/testdata/golden/package-index.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,16 @@ Arduino Lint provides 1 rules for the [`package-index`](https://arduino.github.i
22

33
---
44

5-
<a id="IS001"></a>
5+
<a id="IA004"></a>
66

7-
## missing (`IS001`)
7+
## packages[\*].name missing (`IA004`)
88

9-
No package index file was found in the specified project path.
9+
The package index has a package without a `name` property.
1010

11-
More information: [**here**](https://arduino.github.io/arduino-cli/latest/package_index_json-specification/)<br />
11+
More information: [**here**](https://arduino.github.io/arduino-cli/latest/package_index_json-specification/#json-index-file-contents)<br />
1212
Enabled for superproject type: all<br />
1313
Category: data<br />
14-
Subcategory: general
14+
Subcategory: package
1515

1616
##### Rule levels
1717

0 commit comments

Comments
 (0)