Publish generated list of rules on documentation website by per1234 · Pull Request #261 · arduino/arduino-lint (original) (raw)

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

• 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. In order for the project infrastructure to support this supplemental module, I synced with the latest versions of the relevant "template" assets, which have had that very capability added since the time of the last sync.

The existing structure and content of the rule configurations was not sufficient for this new usage, so I adjusted and expanded on them:

• Add dedicated field for reference URLs and add references to rules that did not already have one where appropriate
• Add or expand the contents of the Description field.
  • This content is now written in Markdown. Its existing use is limited to the JSON format output. Since the Markdown syntax is very lightweight and intuitive, and any reader of the JSON format output will already have been presented with plenty of syntax, I don't think the change has a harmful effect on that output.

Demo: https://per1234.github.io/arduino-lint/dev/rules/

Resolves #158