Publish generated list of rules on documentation website

This will provide a convenient reference for information about the rules Arduino Lint applies to projects.

- More verbose description of the rule than would be appropriate for the command line output.
- Link to the reference information that will allow the reader to fully understand the cause of the rule violation and
  how to fix it.
- Table showing the rule violation level (i.e., error/warning/disabled) vs. common tool configuration.

I added a bespoke "Rules > Introduction" page to give some general information about the rule system. , but the "Sketch",
"Library", "Platform", and "Package index" pages are all auto-generated from the Arduino Lint source code and will be
automatically updated any time rules are added or modified without any additional effort.

The rule documentation content is generated by the "ruledocsgen" Go program, which is a separate module, located in its
own subfolder of the repository, similar to the standardized "docsgen" program that generates the command line reference.

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

@@ -62,6 +62,7 @@ jobs:
         module:
           - path: ./
           - path: docsgen
+          - path: ruledocsgen
 
     steps:
       - name: Checkout repository
@@ -96,6 +97,7 @@ jobs:
         module:
           - path: ./
           - path: docsgen
+          - path: ruledocsgen
 
     steps:
       - name: Checkout repository
@@ -133,6 +135,7 @@ jobs:
         module:
           - path: ./
           - path: docsgen
+          - path: ruledocsgen
 
     steps:
       - name: Checkout repository
@@ -170,6 +173,7 @@ jobs:
         module:
           - path: ./
           - path: docsgen
+          - path: ruledocsgen
 
     steps:
       - name: Checkout repository
@@ -207,6 +211,7 @@ jobs:
         module:
           - path: ./
           - path: docsgen
+          - path: ruledocsgen
 
     steps:
       - name: Checkout repository

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

@@ -18,6 +18,7 @@ on:
       - "pyproject.toml"
       - "docs/**"
       - "docsgen/**"
+      - "ruledocsgen/**"
       - "**.go"
   pull_request:
     paths:
@@ -28,6 +29,7 @@ on:
       - "pyproject.toml"
       - "docs/**"
       - "docsgen/**"
+      - "ruledocsgen/**"
       - "**.go"
   workflow_dispatch:
   repository_dispatch:

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

@@ -20,6 +20,7 @@ on:
       - "Taskfile.ya?ml"
       - "**.go"
       - "docsgen/**"
+      - "ruledocsgen/**"
       - "mkdocs.ya?ml"
       - "poetry.lock"
       - "pyproject.toml"

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

@@ -69,6 +69,8 @@ jobs:
         module:
           - path: ./
             codecov-flags: unit
+          - path: ruledocsgen/
+            codecov-flags: unit
 
     runs-on: ${{ matrix.operating-system }}
 

.gitignore

@@ -18,5 +18,8 @@ coverage_unit.txt
 /docsgen/arduino-cli
 /docsgen/arduino-cli.exe
 /docs/commands/*.md
+/ruledocsgen/ruledocsgen
+/ruledocsgen/ruledocsgen.exe
+/docs/rules/
 
 /dist

.prettierignore

@@ -9,3 +9,4 @@
 /internal/project/projectdata/testdata/packageindexes/invalid-JSON/package_foo_index.json
 /internal/rule/rulefunction/testdata/packageindexes/invalid-JSON/package_foo_index.json
 /internal/rule/rulefunction/testdata/sketches/InvalidJSONMetadataFile/sketch.json
+/ruledocsgen/testdata/golden

Taskfile.yml

@@ -106,6 +106,7 @@ tasks:
     desc: Create all generated documentation content
     deps:
       - task: go:cli-docs
+      - task: go:rule-docs
       # Make the formatting consistent with the non-generated Markdown
       - task: general:format-prettier
 
@@ -198,6 +199,20 @@ tasks:
           {{default "-min_confidence 0.8 -set_exit_status" .GO_LINT_FLAGS}} \
           {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}}
 
+  go:rule-docs:
+    desc: Generate rules documentation
+    dir: ./ruledocsgen
+    deps:
+      - task: go:rule-docs:build
+    cmds:
+      - ./ruledocsgen ../docs/rules
+
+  go:rule-docs:build:
+    desc: Generate rules documentation
+    dir: ./ruledocsgen
+    cmds:
+      - go build
+
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-task/Taskfile.yml
   go:test:
     desc: Run unit tests
@@ -217,9 +232,11 @@ tasks:
     desc: Run integration tests
     deps:
       - task: go:build
+      - task: go:rule-docs:build
       - task: poetry:install-deps
     cmds:
       - poetry run pytest tests
+      - poetry run pytest ruledocsgen/tests
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:vet:

docs/index.md

@@ -1,8 +1,8 @@
 **Arduino Lint** is a command line tool that checks for common problems with [Arduino](https://www.arduino.cc/)
 projects.
 
-Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. Rules cover
-specification compliance, Library Manager submission requirements, and best practices.
+Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. [Rules](rules.md)
+cover specification compliance, Library Manager submission requirements, and best practices.
 
 ## Installation
 

docs/rules.md

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

mkdocs.yml

@@ -22,6 +22,7 @@ markdown_extensions:
       guess_lang: false
   - markdown.extensions.toc:
       permalink: true
+      toc_depth: 4
   - mdx_truly_sane_lists:
       nested_indent: 2
       truly_sane: true
@@ -44,6 +45,12 @@ nav:
   - Home: index.md
   - installation.md
   - Command reference: commands/arduino-lint.md
+  - Rules:
+      - Introduction: rules.md
+      - Sketch: rules/sketch.md
+      - Library: rules/library.md
+      - Platform: rules/platform.md
+      - Package index: rules/package-index.md
   - CONTRIBUTING.md
 
 extra:

ruledocsgen/go.mod

@@ -0,0 +1,12 @@
+module github.com/arduino/arduino-lint/ruledocsgen
+
+go 1.16
+
+replace github.com/arduino/arduino-lint => ../
+
+require (
+	github.com/arduino/arduino-lint v0.0.0
+	github.com/arduino/go-paths-helper v1.6.1
+	github.com/olekukonko/tablewriter v0.0.5
+	github.com/stretchr/testify v1.7.0
+)