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

‎ruledocsgen/go.mod

Lines changed: 1 addition & 0 deletions
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

‎ruledocsgen/go.sum

Lines changed: 8 additions & 0 deletions
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=

‎ruledocsgen/main.go

Lines changed: 9 additions & 2 deletions
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

‎ruledocsgen/main_test.go

Lines changed: 7 additions & 7 deletions
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

‎ruledocsgen/testdata/golden/package-index.md

Lines changed: 5 additions & 5 deletions
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)