Skip to content

Publish generated list of rules on documentation website #261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Aug 26, 2021
Merged

Publish generated list of rules on documentation website #261

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
bed7e04
Avoid workflow conditional reliance on specific runner
per1234 Aug 25, 2021
8096c62
Add multi-module support to project infrastructure
per1234 Aug 25, 2021
ac6f9a3
Add reference URL field to rule configuration
per1234 Aug 23, 2021
453a178
Update reference URLs
per1234 Aug 23, 2021
f532a1a
Add missing rule reference URLs
per1234 Aug 23, 2021
d126e70
Add and expand rule descriptions
per1234 Aug 23, 2021
8aca928
Add test for empty required rule configuration fields
per1234 Aug 24, 2021
13d8760
Publish generated list of rules on documentation website
per1234 Aug 24, 2021
5fc2ed4
Use different syntax style for arbitrary array elements in rule descr…
per1234 Aug 26, 2021
f62a372
Escape Markdown markup in rule reference Brief text
per1234 Aug 26, 2021
fbda05e
Refer to the platform "extra_flags" properties in a less confusing ma…
per1234 Aug 26, 2021
ff3b56a
Use a different term when referring to additional data properties in …
per1234 Aug 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
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.
  • Loading branch information
@per1234
per1234 committed Aug 26, 2021
commit f62a372afffd82dc31ce1e8bf8bd9f06aa6b51a1
1 change: 1 addition & 0 deletions ruledocsgen/go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ go 1.16
replace github.com/arduino/arduino-lint => ../

require (
github.com/JohannesKaufmann/html-to-markdown v1.3.0
github.com/arduino/arduino-lint v0.0.0
github.com/arduino/go-paths-helper v1.6.1
github.com/olekukonko/tablewriter v0.0.5
Expand Down
8 changes: 8 additions & 0 deletions ruledocsgen/go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym
github.com/DATA-DOG/go-sqlmock v1.3.3/go.mod h1:f/Ixk793poVmq4qj/V1dPUg2JEAKC73Q5eFN3EC/SaM=
github.com/DataDog/datadog-go v4.0.0+incompatible/go.mod h1:LButxg5PwREeZtORoXG3tL4fMGNddJ+vMq1mwgfaqoQ=
github.com/GeertJohan/go.incremental v1.0.0/go.mod h1:6fAjUhbVuX1KcMD3c8TEgVUqmo4seqhv0i0kdATSkM0=
github.com/JohannesKaufmann/html-to-markdown v1.3.0 h1:K/p4cq8Ib13hcSVcKQNfKCSWw93CYW5pAjY0fl85has=
github.com/JohannesKaufmann/html-to-markdown v1.3.0/go.mod h1:JNSClIRYICFDiFhw6RBhBeWGnMSSKVZ6sPQA+TK4tyM=
github.com/Masterminds/semver v1.4.2/go.mod h1:MB6lktGJrhw8PrUyiEoblNEGEQ+RzHPF078ddwwvV3Y=
github.com/Masterminds/semver/v3 v3.0.3/go.mod h1:VPu/7SZ7ePZ3QOrcuXROw5FAcLl4a0cBrbBpGY/8hQs=
github.com/Microsoft/go-winio v0.4.11/go.mod h1:VhR8bwka0BXejwEJY73c50VrPtXAaKcyvVC4A4RozmA=
Expand All @@ -58,6 +60,7 @@ github.com/OneOfOne/xxhash v1.2.8 h1:31czK/TI9sNkxIKfaUfGlU47BAxQ0ztGgd9vPyqimf8
github.com/OneOfOne/xxhash v1.2.8/go.mod h1:eZbhyaAYD41SGSSsnmcpxVoRiQ/MPUTjUdIIOT9Um7Q=
github.com/ProtonMail/go-crypto v0.0.0-20210428141323-04723f9f07d7 h1:YoJbenK9C67SkzkDfmQuVln04ygHj3vjZfd9FL+GmQQ=
github.com/ProtonMail/go-crypto v0.0.0-20210428141323-04723f9f07d7/go.mod h1:z4/9nQmJSSwwds7ejkxaJwO37dru3geImFUdJlaLzQo=
github.com/PuerkitoBio/goquery v1.5.1/go.mod h1:GsLWisAFVj4WgDibEWF4pvYnkVQBpKBKeU+7zCJoLcc=
github.com/PuerkitoBio/purell v1.1.0/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
Expand All @@ -72,6 +75,7 @@ github.com/alcortesm/tgz v0.0.0-20161220082320-9c5fe88206d7 h1:uSoVVbwJiQipAclBb
github.com/alcortesm/tgz v0.0.0-20161220082320-9c5fe88206d7/go.mod h1:6zEj6s6u/ghQa61ZWa/C2Aw3RkjiTBOix7dkqa1VLIs=
github.com/alecthomas/template v0.0.0-20160405071501-a0175ee3bccc/go.mod h1:LOuyumcjzFXgccqObfd/Ljyb9UuFJ6TxHnclSeseNhc=
github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRFXyAe+OPACYpWeL0wqObRcbAqCMya13uyzqw0=
github.com/andybalholm/cascadia v1.1.0/go.mod h1:GsXiBklL0woXo1j/WYWtSYYC4ouU9PqHO0sqidkEA4Y=
github.com/anmitsu/go-shlex v0.0.0-20161002113705-648efa622239/go.mod h1:2FmKhYUyUczH0OGQWaF5ceTx0UBShxjsH6f8oGKYe2c=
github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be h1:9AeTilPcZAjCFIImctFaOjnTIavg87rW78vTPkQqLI8=
github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be/go.mod h1:ySMOLuWl6zY27l47sB3qLNK6tF2fkHG55UZxx8oIVo4=
Expand Down Expand Up @@ -1079,6 +1083,7 @@ github.com/schollz/closestmatch v2.1.0+incompatible/go.mod h1:RtP1ddjLong6gTkbtm
github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529/go.mod h1:DxrIzT+xaE7yg65j358z/aeFdxmN0P9QXhEzd20vsDc=
github.com/seatgeek/logrus-gelf-formatter v0.0.0-20210219220335-367fa274be2c h1:jwWrlqKHQeSRjTskQaHBtCOWbaMsd54NBAnofYbEHGs=
github.com/seatgeek/logrus-gelf-formatter v0.0.0-20210219220335-367fa274be2c/go.mod h1:/THDZYi7F/BsVEcYzYPqdcWFQ+1C2InkawTKfLOAnzg=
github.com/sebdah/goldie/v2 v2.5.1/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
github.com/segmentio/analytics-go v3.0.1+incompatible/go.mod h1:C7CYBtQWk4vRk2RyLu0qOcbHJ18E3F1HV2C/8JvKN48=
github.com/segmentio/analytics-go v3.1.0+incompatible/go.mod h1:C7CYBtQWk4vRk2RyLu0qOcbHJ18E3F1HV2C/8JvKN48=
github.com/segmentio/backo-go v0.0.0-20160424052352-204274ad699c/go.mod h1:kJ9mm9YmoWSkk+oQ+5Cj8DEoRCX2JT6As4kEtIIOp1M=
Expand Down Expand Up @@ -1221,6 +1226,7 @@ github.com/xtgo/uuid v0.0.0-20140804021211-a0b114877d4c/go.mod h1:UrdRz5enIKZ63M
github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.2.0/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
github.com/zenazn/goji v0.9.0/go.mod h1:7S9M489iMyHBNxwZnk9/EHS098H4/F6TATF2mIxtB1Q=
Expand Down Expand Up @@ -1364,6 +1370,7 @@ golang.org/x/mod v0.4.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/mod v0.4.1/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/mod v0.4.2 h1:Gz96sIWK3OalVv/I/qNygP42zyoKp3xptRVCWRFEBvo=
golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/net v0.0.0-20180218175443-cbe0f9307d01/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180406214816-61147c48b25b/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180816102801-aaf60122140d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
Expand Down Expand Up @@ -1405,6 +1412,7 @@ golang.org/x/net v0.0.0-20200219183655-46282727080f/go.mod h1:z5CRVTTTmAJ677TzLL
golang.org/x/net v0.0.0-20200222125558-5a598a2470a0/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20200301022130-244492dfa37a/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20200320220750-118fecf932d8/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20200324143707-d3edc9973b7e/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
golang.org/x/net v0.0.0-20200501053045-e0ff5e5a1de5/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
golang.org/x/net v0.0.0-20200506145744-7e3656a0809f/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
Expand Down
11 changes: 9 additions & 2 deletions ruledocsgen/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import (
"os"
"text/template"

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

templateFunctions := template.FuncMap{
// Some the rule config text is intended for use in both tool output and in the reference, so can't be formatted at
// the source as Markdown. Incidental markup characters in that text must be escaped.
"escape": escape.MarkdownCharacters,
}

projectRulesIntroTemplate := template.Must(template.New("messageTemplate").Parse(
"Arduino Lint provides {{.RuleCount}} rules for the [`{{.ProjectType}}`]({{.ProjectTypeReference}}) project type:\n",
))
ruleDocumentationTemplate := template.Must(template.New("messageTemplate").Parse(`
ruleDocumentationTemplate := template.Must(template.New("messageTemplate").Funcs(templateFunctions).Parse(`
---

<a id="{{.ID}}"></a>

## {{.Brief}} (` + "`" + `{{.ID}}` + "`" + `)
## {{escape .Brief}} (` + "`" + `{{.ID}}` + "`" + `)

{{.Description}}

Expand Down
14 changes: 7 additions & 7 deletions ruledocsgen/main_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,18 +111,18 @@ func TestAll(t *testing.T) {
ProjectType: projecttype.PackageIndex,
SuperprojectType: projecttype.All,
Category: "data",
Subcategory: "general",
ID: "IS001",
Brief: "missing",
Description: "No package index file was found in the specified project path.",
MessageTemplate: "No package index was found in specified project path.",
Reference: "https://arduino.github.io/arduino-cli/latest/package_index_json-specification/",
Subcategory: "package",
ID: "IA004",
Brief: "packages[*].name missing",
Description: "The package index has a package without a `name` property.",
MessageTemplate: "Missing packages[*].name property in package(s): {{.}}",
Reference: "https://arduino.github.io/arduino-cli/latest/package_index_json-specification/#json-index-file-contents",
DisableModes: nil,
EnableModes: []rulemode.Type{rulemode.Default},
InfoModes: nil,
WarningModes: nil,
ErrorModes: []rulemode.Type{rulemode.Default},
RuleFunction: rulefunction.PackageIndexMissing,
RuleFunction: rulefunction.PackageIndexPackagesNameMissing,
},
}

Expand Down
10 changes: 5 additions & 5 deletions ruledocsgen/testdata/golden/package-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@ Arduino Lint provides 1 rules for the [`package-index`](https://arduino.github.i

---

<a id="IS001"></a>
<a id="IA004"></a>

## missing (`IS001`)
## packages[\*].name missing (`IA004`)

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

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

##### Rule levels

Expand Down