Linter for plugin documentation

[reimda]

Documentation of each plugin is in readme.md in the plugin folder. To make them easier to use, we try to keep the structure of the readme.md files similar for all plugins. They should always include a short description of the purpose of the plugin, a sample of its toml configuration, and a description of the plugin's metric format. They can optionally have compatibility notes and other sections.

Since many people edit the plugin docs it is hard to keep the structure similar. Let's add a linter that parses the markdown and checks that the expected sections are present. Since the sample toml config is also kept in the plugin's source code, the linter could also check that the two copies match.

There are other things a linter could do, such as check that all the toml settings that the plugin accepts are documented in the sample config.

This should also make code reviews of plugin changes more simple and help contributors of new plugins know what is required for documentation

[powersj]

next steps: @reimda to bring the final PR(s) home and land 'em!

[reimda]

Here's a summary of related work:

PRs merged:

• add linter - chore: add readme linter #10916
• run linter in CI - chore: add readme linter to CI #11020
• clean up output readmes - chore: Fix readme linter errors for output plugins #10951

PRs to be merged:

• clean up processor and aggregator readmes - chore: Fix readme linter errors for processor, aggregator, and parser plugins #10960
• clean up input readmes a-d - chore: Fix readme linter errors for input plugins A-D #10964

no PR yet:

• clean up input readmes e-z

We're currently moving plugin sample configs to be in separate files (#11136 and related). Since that task also requires touching every readme, it makes sense not to do it at the same time as cleaning up the readme linter errors. Moving sample configs should be done in a few days. When it's done I'll continue cleaning up readme linter errors.

[powersj]

Moving sample configs should be done in a few days. When it's done I'll continue cleaning up readme linter errors.

FYI @srebhan has completed these.

[reimda]

• chore: Fix readme linter errors for input plugins E-L #11214

[reimda]

• chore: Fix readme linter errors for input plugins M-Z #11274

[sspaink]

@reimda I think this is done?

[reimda]

Yes it's done